Skip to content

FAQ

Jump to bottom
Tom Planche edited this page Aug 30, 2026 · 12 revisions

Frequently Asked Questions

This page answers common questions about Rona. If you don't find your question here, please check the GitHub Issues or create a new one.

Installation

How do I install Rona?

On macOS and Linux, Homebrew is the easiest way:

brew install rona-rs/rona/rona

With a Rust toolchain, cargo binstall fetches a pre-built binary and skips the compile:

cargo binstall rona

cargo install rona also works, but it compiles from source.

For more details, see the Installation guide.

What are the system requirements?

  • Rust 2024 edition or later
  • Git 2.23 or later
  • A supported shell (Bash, Fish, Zsh, or PowerShell)

How do I update Rona?

To update Rona to the latest version:

cargo binstall --force rona   # or: cargo install rona --force

With Homebrew, use brew upgrade rona.

Usage

How do I initialize Rona?

Initialize Rona with your preferred editor:

# Initialize with Vim
rona init vim

# Initialize with Zed
rona init zed

# Initialize with default editor (nano)
rona init

How do I stage files with exclusions?

Use the -a flag with patterns:

# Exclude Rust files
rona -a "*.rs"

# Exclude multiple file types
rona -a "*.rs" "*.tmp" "*.log"

How do I unstage files?

Use rona reset. It is non-destructive: working-tree edits are always preserved.

# Unstage everything currently staged (like git reset)
rona reset

# Unstage a single file
rona reset src/main.rs

# Pick staged files to unstage from a checklist
rona reset -i

How do I discard working-tree changes?

Use rona restore. It is destructive, so it prompts for confirmation first (skip with -y). Untracked files are never touched.

# Discard changes to a file (prompts for confirmation)
rona restore src/main.rs

# Pick changed files to discard from a checklist
rona restore -i

# Skip the confirmation prompt
rona restore -y src/main.rs

Running rona restore with no files and no -i is a deliberate no-op that prints a hint, since discarding every change at once is rarely intended.

How do I generate a commit message?

Use the -g flag:

# Standard mode (opens editor)
rona -g

# Interactive mode (input in terminal)
rona -g -i

# Without commit number
rona -g -n

# Interactive without commit number
rona -g -i -n

# Preview what would be generated
rona -g --dry-run

Interactive mode details (-g -i):

  • Shows the commit type selector (uses configured types or defaults)
  • Prompts for any configured extra fields and the message, in the order defined by field_order
  • Formats the message using your configured template (or the built-in default)
  • Saves directly to commit_message.md without file details

No commit number mode (-g -n):

  • Excludes the {commit_number} variable from the template
  • Works with both editor and interactive modes

How do I commit and push?

Use the -c and -p flags:

# Commit
rona -c

# Commit and push
rona -c -p

# Auto-confirm without prompts (useful for automation)
rona -c -y

# Copy commit message to clipboard
rona -c --copy

# Create an unsigned commit (explicitly disable signing)
rona -c -u
# or
rona -c --unsigned

# Unsigned commit with push
rona -c -u -p

# Preview (dry run) what would be committed
rona -c --dry-run

Notes:

  • By default, Rona auto-detects GPG availability and signs commits if possible. Use -u/--unsigned to disable signing explicitly.
  • The --yes flag skips confirmation prompts, useful for CI/CD workflows.
  • The --copy flag copies the commit message to your clipboard.

How do I create a branch interactively?

Use the branch command:

rona branch

Rona prompts for the branch type and any configured extra fields, then creates and checks out the branch. Use --dry-run to preview the name without creating it, or --no-switch to create it without switching.

How do I configure branch name templates?

Add branch_template and optionally branch_types and [[branch_extra_fields]] to your .rona.toml. All top-level branch keys must appear before any [[branch_extra_fields]] entry.

branch_template = "{branch_type}/{service}/{version}"
branch_types = ["staging", "production"]
branch_field_order = ["service", "version"]

[[branch_extra_fields]]
name = "service"
prompt = "Service name"

[[branch_extra_fields]]
name = "version"
prompt = "Version"
prefetch.source = "branches"
prefetch.extract_regex = "[0-9]+(?:-[0-9]+)+"
prefetch.deduplicate = true

Rona only shows a prompt for {branch_type} and {description} when those variables actually appear in the template. A template like release/{version} skips both and only asks for version.

What is merge_branch_and_commit_types?

Setting merge_branch_and_commit_types = true appends your commit_types values to the branch_types selector (excluding duplicates), so you don't have to maintain two separate lists. branch_types must still be defined; omitting it while setting this key produces a clear error.

What is prefetch.source = "branches"?

It scans all local branch names and applies extract_regex to each, giving you a select list populated with values already present in the repo (for example version strings from existing branches). It is mainly useful in [[branch_extra_fields]].

How do I open a pull request?

Run rona pr on your feature branch. Rona writes the request to pr_description.md, opens your editor, pushes the branch, and opens the request.

rona pr
rona pr --draft --target develop
rona pr --dry-run            # Preview without opening anything

rona mr and rona pull-request are aliases of the same command.

How does rona pr decide the title?

The first # Heading of the document is the title. Everything below it is the description. A new document starts with a heading built from pr_title_template, which defaults to the subject of the last commit. Edit it in place, or pass --title to override it.

Which backend does rona pr use?

Rona reads the forge from the remote URL, then picks a backend from the binaries you have. GitHub uses gh, or a web form without it. GitLab uses glab, or GitLab push options without it. Bitbucket uses a web form.

Force one with --backend gh, --backend glab, --backend push-options, or --backend browser. --web is the short form of the last one. Set pr_backend to make the choice permanent.

rona pr says it cannot tell which forge my host is

Rona reads the forge from the hostname. A self-hosted instance at git.company.com does not name its product, so set the forge yourself:

# .rona.toml
pr_forge = "gitlab"

Where does the description template come from?

Rona looks for the request template of the repository, under .github/PULL_REQUEST_TEMPLATE.md or .gitlab/merge_request_templates/. With several templates, it asks which one to use. With none, the file starts with the heading alone.

Does pr_description.md end up in a commit?

No. Rona adds it to .git/info/exclude the first time it writes the file.

Configuration

How do I change the default editor?

Use the set-editor command:

rona set-editor vim

How do I set up shell completion?

See the Shell Integration guide for detailed instructions for your shell.

How do I configure file patterns?

Create a .commitignore file in your repository root with patterns to exclude.

Where is the configuration file located?

Rona reads configuration from multiple locations (in order of priority):

  1. Project-level: .rona.toml (in your repository root) - highest priority
  2. Any file the project config pulls in via extends
  3. Any file pulled in by a matching [[overrides]] entry declared in a global config
  4. User-level: ~/.config/rona.toml
  5. Legacy path: ~/.config/rona/config.toml (supported for backward compatibility)
  6. Built-in defaults - lowest priority

How do I apply one config to every repository under a directory?

Declare an [[overrides]] entry in your global config. Any time Rona runs from a directory matching path, the file named by config is layered in on top of your global settings, without those repositories needing a .rona.toml:

# ~/.config/rona.toml
[[overrides]]
path = "~/work/**"
config = "~/work/shared-rona.toml"

The pattern matches the directory Rona runs from, so it applies from any subdirectory of a covered repository. A project's own .rona.toml still wins over the override. See Configuration for the full matching rules.

How do I check which configuration file is being used?

Use the config which subcommand:

# See which config file is active
rona config which

# View the effective configuration values
rona config which --effective

# Check configuration for a specific path
rona config which /path/to/project

This is helpful for debugging configuration issues and verifying precedence.

What are the default commit types?

Default types:

  • feat, fix, docs, test, chore

You can customize the list in .rona.toml or ~/.config/rona.toml:

commit_types = ["feat", "fix", "docs", "test", "chore", "refactor", "style", "perf"]

How do I customize commit message templates?

Add a template field to your .rona.toml or ~/.config/rona.toml:

# Default template
template = "[{commit_number}] ({commit_type} on {branch_name}) {message}"

# Simple format
template = "{commit_type}: {message}"

# With timestamp
template = "[{date} {time}] {commit_type}: {message}"

Available variables:

  • {commit_number}, {commit_type}, {branch_name}, {message}, {date}, {time}, {author}, {email}
  • Any extra field name defined under [[extra_fields]] (e.g. {scope}, {ticket})

How do I use conditional blocks in templates?

Conditional blocks allow content to render only when a variable has a value:

# Syntax: {?variable}content{/variable}
template = "{?commit_number}[{commit_number}] {/commit_number}({commit_type}) {message}"

This prevents empty brackets when using the -n flag:

  • With commit number: [5] (feat) Add feature
  • Without (-n flag): (feat) Add feature

Instead of: [] (feat) Add feature

How do I add project-specific prompts (scope, ticket, etc.)?

Use [[extra_fields]] in your .rona.toml. Each entry adds one interactive prompt, and its value becomes a template variable.

# Must appear BEFORE any [[extra_fields]] entry
template = "{commit_type}{?scope}({scope}){/scope}: {message}{?ticket} [{ticket}]{/ticket}"

# Scope — suggested from recent commits
[[extra_fields]]
name = "scope"
kind = "select"
prefetch.source = "command"
prefetch.command = "git log -20 --pretty=format:%s"
prefetch.extract_regex = "\\w+\\((?P<value>[^)]*)\\):"
prefetch.deduplicate = true

# Ticket — default extracted from branch name (e.g. feat/PROJ-42_add-login → PROJ-42)
[[extra_fields]]
name = "ticket"
kind = "text"
validation = "^[A-Z]+-[0-9]+$"
prefetch.source = "branch"
prefetch.extract_regex = "[A-Z]+-[0-9]+"

See the Features page for the full field reference.

How do I control the order of prompts in interactive mode?

Use field_order — an array of prompt names. The reserved name "message" positions the built-in message prompt among your extra fields. Extra fields not listed are appended at the end.

# Show message first, then scope, then ticket
field_order = ["message", "scope", "ticket"]

The default (empty field_order) shows extra fields first, then message.

How do I enable verbose mode?

Add the -v or --verbose flag before any command:

# Verbose commit and push
rona -v -c -p

# Verbose sync operation
rona -v sync -r

# Verbose with file staging
rona -v -a "src/"

Verbose mode shows detailed operation information, useful for debugging and CI/CD troubleshooting.

How do I use a custom configuration file?

Use the -f/--config-file global flag to load a specific TOML file instead of the normal hierarchy. The flag can appear before or after the subcommand:

# Use a custom config file
rona -f /path/to/custom.toml -g

# Combine with other commands
rona -f ./team-config.toml -c -p

# Flag after the subcommand is also valid
rona branch -f .rona-release.toml

# Use with verbose mode
rona -v -f ./custom.toml -g

This is useful for:

  • Team-specific configuration templates
  • Testing different configurations
  • CI/CD environments
  • Multi-project workflows

How do I use dry-run mode?

Most commands support --dry-run to preview changes without executing them:

# Preview what would be staged
rona -a "*.rs" --dry-run

# Preview commit message generation
rona -g --dry-run

# Preview what would be committed
rona -c --dry-run

# Preview what would be pushed
rona -p --dry-run

# Preview config initialization
rona init vim --dry-run

Troubleshooting

Editor not opening

  1. Check if the editor is properly configured:
rona set-editor vim
  1. Verify the editor is installed
  2. Try using a different editor

Pattern exclusion not working

  1. Verify pattern syntax
  2. Check for typos
  3. Ensure patterns are properly quoted

Commit message issues

  1. Check file permissions
  2. Verify editor configuration
  3. Try interactive mode (rona -g -i)
  4. Use verbose mode to see detailed operations (rona -v -g)

Configuration not taking effect

  1. Check which config file is being used:
rona config which
  1. Verify effective configuration values:
rona config which --effective
  1. Check configuration precedence (project-level overrides global)
  2. Try using verbose mode to debug:
rona -v -g

Development

How do I contribute?

See the Contributing guide for detailed instructions.

How do I run tests?

cargo test

How do I build from source?

git clone https://github.com/rona-rs/rona.git
cd rona
cargo build --release

Common Issues

Permission Denied

If you get a permission denied error:

  1. Check file permissions
  2. Verify you have write access
  3. Try running with sudo (if appropriate)

Command Not Found

If Rona is not found:

  1. Verify installation
  2. Check PATH environment
  3. Reinstall if necessary

Editor Issues

If you have editor-related issues:

  1. Check editor installation
  2. Verify editor configuration
  3. Try a different editor

Best Practices

Commit Messages

  • Use clear and descriptive messages
  • Follow conventional commit format
  • Reference issue numbers when applicable

File Staging

  • Use specific patterns for exclusion
  • Review staged files before committing
  • Keep exclusion patterns in version control

Branch Management

  • Use feature branches for new features
  • Keep branches up to date with main
  • Delete branches after merging

Getting Help

Where can I get help?

  • Check the GitHub Issues
  • Join the community
  • Ask for help in issues

How do I report a bug?

  1. Check if the bug is already reported
  2. Create a new issue
  3. Provide detailed information
  4. Include reproduction steps

How do I request a feature?

  1. Check if the feature is already requested
  2. Create a new issue
  3. Describe the feature
  4. Explain the use case

Next Steps

zoizo

Clone this wiki locally