Command Reference

This page provides a comprehensive reference for all Rona commands and their options.

Core Commands

`branch`

Interactively generate a branch name from a configurable template and create the branch.

rona branch [OPTIONS]

Options:

--dry-run - Preview the generated branch name without creating the branch
--no-switch - Create the branch without switching to it

Behavior:

Reads branch_template from configuration (defaults to {branch_type}/{description})
Only prompts for {branch_type} when the template references it
Only prompts for {description} when the template references it
Prompts for any branch_extra_fields entries referenced in the template
Branch type selector is always labeled "Select branch type", drawing from branch_types (or commit_types when merge_branch_and_commit_types = true)

Examples:

# Interactive branch creation with default template
rona branch

# Preview the branch name without creating it
rona branch --dry-run

# Create branch without switching to it
rona branch --no-switch

# Use a dedicated release config file
rona -f .rona-release.toml branch

Example session (with template {branch_type}/{service}/{version}):

> Select branch type   staging
> Service name         scrapers
> Version              2-15-6

Result: branch staging/scrapers/2-15-6 created and checked out.

`add-with-exclude` (`-a`)

Add files to Git staging while excluding specified patterns, or pick files interactively from a checklist.

rona add-with-exclude <pattern(s)> [--dry-run]
# or
rona -a <pattern(s)> [--dry-run]
# or interactively
rona -a -i [--dry-run]

Options:

-i, --interactive - Pick which changed files to stage from a checklist instead of using exclude patterns
--dry-run - Preview what files would be added without actually staging them

Examples:

# Exclude Rust and temporary files
rona -a "*.rs" "*.tmp"

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

# Pick files to stage from a MultiSelect checklist
rona -a -i

Interactive mode (-i):

Instead of describing what to leave out with exclude patterns, pick exactly what to stage from a checklist of changed files (similar to git add -p or the lazygit file selector). Untracked, modified, type-changed and deleted files are all listed with a short status label:

> Select files to stage
  [x] modified    src/cli.rs
  [ ] untracked   notes.txt
  [x] deleted     old_module.rs
  [ ] modified    README.md

Use the arrow keys to move, space to toggle a file, and enter to confirm. When -i is used, any exclude patterns are ignored.

`commit` (`-c`)

Commit changes using prepared message.

rona commit [OPTIONS] [extra args]
# or
rona -c [-p | --push] [-u | --unsigned] [-y | --yes] [--copy] [--dry-run] [extra args]

Options:

-p, --push - Push after committing
-u, --unsigned - Disable GPG commit signing
-y, --yes - Auto-confirm commit without prompting
--copy - Copy commit message to clipboard
--dry-run - Preview what would be committed without committing

Default behavior:

Automatically detects GPG availability and signs commits if possible.
- Use -u/--unsigned to explicitly disable signing.

Examples:

# Auto-detected signing (default behavior)
rona -c

# Explicitly unsigned commit
rona -c -u

# Commit and push (with auto-detected signing)
rona -c -p

# Auto-confirm without prompting
rona -c -y

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

# Explicitly unsigned commit with push
rona -c -u -p

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

`completion`

Generate shell completion scripts.

rona completion <shell>

Supported shells: bash, fish, zsh, powershell

Example:

rona completion fish > ~/.config/fish/completions/rona.fish

`config`

Manage configuration files and inspect which ones are active. Groups two subcommands:

`config create` (`-c`)

Create a local or global configuration file.

rona config create <local|global> [--exclude] [--dry-run]
# short form
rona config -c <local|global> [-e] [--dry-run]

Options:

-e, --exclude - Add .rona.toml to .git/info/exclude (local scope only)
--dry-run - Preview what would be created without writing any files

Examples:

# Create a local project configuration
rona config create local
rona config -c local

# Create and exclude .rona.toml from git tracking
rona config create local --exclude
rona config -c local -e

# Create a global user configuration
rona config create global
rona config -c global

# Preview without writing
rona config create local --dry-run

Behavior:

Creates a configuration file with default settings if it doesn't exist
If the file already exists, displays a message and suggests using rona set-editor to modify settings
Automatically creates parent directories if needed (for global config)
Generated config files use TOML format with default values for editor, commit types, and template
--exclude adds .rona.toml to .git/info/exclude, keeping it untracked without modifying .gitignore

`config which` (`-w`)

Show which configuration files would be loaded from the current (or given) directory, in priority order.

rona config which [PATH] [--effective]
# short form
rona config -w [PATH] [-e | --effective]

Options:

-e, --effective - Also print the merged configuration values

Examples:

# Show config sources for the current directory
rona config which
rona config -w

# Show config sources from a specific path
rona config which /path/to/project

# Show config sources and their merged values
rona config which --effective
rona config -w -e

Output:

Each row shows a config layer, its priority, whether it exists, and where it came from. Layers pulled in by a [[overrides]] entry are labelled with the path pattern that matched the current directory:

  ○ [priority 1] /Users/you/.config/rona/config.toml
    └─ Legacy global config (not found)
  ✓ [priority 2] /Users/you/.config/rona.toml
    └─ Global config (active)
  ✓ [priority 3] /Users/you/Affluences/afl-notes/selfnotes.config
    └─ Override config (path = "~/Affluences/**") (active)
  ○ [priority 5] /Users/you/Affluences/some-repo/.rona.toml
    └─ Project config (not found)

Priority is a layer identifier, not a row number, so gaps in the sequence are normal (priority 4 is the project config's extends chain, absent above).

Use Cases:

Debugging configuration issues
Verifying which config file takes precedence (local vs global)
Checking which [[overrides]] entries match the current directory, and which pattern pulled each one in
Checking effective configuration values

`generate` (`-g`)

Generate or update commit message template.

rona generate [--interactive] [--no-commit-number] [--dry-run]
# or
rona -g [-i | --interactive] [-n | --no-commit-number] [--dry-run]

Features:

Creates commit_message.md and .commitignore
Interactive commit type selection
Automatic file change tracking
Interactive mode: Input commit message directly in terminal (-i flag)
Editor mode: Opens in configured editor (default behavior)
No commit number: Exclude commit number from message (-n flag)
Dry run: Preview what would be generated without creating files (--dry-run)

Examples:

# Standard mode: Opens commit type selector, then editor
rona -g

# Interactive mode: Input message directly in terminal
rona -g -i

# Without commit number
rona -g -n

# Interactive mode 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 (using configured types or defaults)
Prompts for any configured extra fields and the message, in the order defined by field_order (default: extra fields first, then message)
Generates a formatted message using your 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
Useful for projects that don't track commit numbers
Works with both interactive and editor modes

`init` (`-i`)

Initialize Rona configuration.

rona init [editor] [--dry-run]  # Any command-line editor (default: nano). Examples: vim, zed, "code --wait"

Options:

--dry-run - Preview what config file would be created without actually creating it

Examples:

# Initialize with vim
rona init vim

# Preview initialization
rona init vim --dry-run

`list-status` (`-l`)

Display repository status (primarily for shell completion).

rona list-status
# or
rona -l

`push` (`-p`)

Push committed changes to remote repository.

rona push [--dry-run] [extra args]
# or
rona -p [--dry-run] [extra args]

Options:

--dry-run - Preview what would be pushed without actually pushing

Examples:

# Push to default remote
rona -p

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

# Push with git options
rona -p --force origin main

`pr` (`mr`, `pull-request`)

Open a pull request, or a merge request on GitLab, for the current branch.

rona pr [OPTIONS]
# or
rona mr [OPTIONS]

One Markdown document holds the whole request. The first # Heading is the title. Everything below it is the description.

Options:

-t, --target <BRANCH> - Branch to target. Defaults to pr_target, then the default branch of the remote
-T, --title <TITLE> - Title of the request. Overrides the document heading
-b, --body-file <PATH> - Markdown file that holds the whole request. Skips the editor
-d, --draft - Open the request as a draft
-l, --label <LABEL> - Label to apply. Repeat the flag for several labels
-r, --reviewer <USER> - Reviewer to request. Repeat the flag for several reviewers
-A, --assignee <USER> - Assignee to set. Repeat the flag for several assignees
--backend <BACKEND> - Backend used to open the request: auto, gh, glab, push-options, or browser
--remote <NAME> - Remote to open the request against. Defaults to pr_remote, then origin
-w, --web - Open the pre-filled web form. Short form of --backend browser
--no-edit - Use the request document as it is, without opening the editor
--no-push - Do not push the source branch before opening the request
-y, --yes - Skip the confirmation prompt
--dry-run - Show what would be opened without opening anything

The target, title, backend, remote, draft state, labels, reviewers, and assignees all have a config counterpart. The flag always wins. See Configuration.

Behavior:

Rona writes the request to pr_description.md at the repository root, then opens your editor
A new file starts from the request template of the repository. With several templates, Rona asks which one to use
The heading of a new file comes from pr_title_template, which defaults to the subject of the last commit
pr_description.md is added to .git/info/exclude, so it never reaches a commit
Rona pushes the source branch before it opens the request. The push-options backend carries the branch itself, so no separate push happens
A confirmation prompt shows the forge, the two branches, the title, and the backend
Rona prints the URL of the request when the backend returns one

Backends:

Backend	How the request is opened
`gh`	`gh pr create`
`glab`	`glab mr create`
`push-options`	`git push -o merge_request.create ...`, GitLab only
`browser`	A pre-filled web form in your browser

With auto, Rona picks the backend from the remote and from the binaries you have:

Forge	Binary present	Backend chosen
GitHub	`gh`	`gh`
GitHub	none	`browser`
GitLab	`glab`	`glab`
GitLab	none	`push-options`
Bitbucket	any	`browser`

Push options need no extra binary and no separate login, so they come before the browser on GitLab.

A backend cannot always carry every field. Rona prints a warning when it drops one. Push options cannot set reviewers. The GitLab web form takes only the branches, the title, and the description. The Bitbucket web form takes only the branches.

When Rona cannot tell which forge a host belongs to, it stops and asks you to set pr_forge or pr_backend.

Description templates:

Rona seeds a new pr_description.md from the templates of the repository:

Forge	Paths searched
GitHub, Bitbucket	`.github/PULL_REQUEST_TEMPLATE.md`, `PULL_REQUEST_TEMPLATE.md`, `docs/PULL_REQUEST_TEMPLATE.md`, and every `.md` file in `.github/PULL_REQUEST_TEMPLATE/`
GitLab	`.gitlab/merge_request_templates/Default.md`, and every `.md` file in `.gitlab/merge_request_templates/`

With no template, the file starts with the heading alone.

Examples:

# Write the request in your editor, then open it
rona pr

# Open a draft against develop
rona pr --draft --target develop

# Add two labels and a reviewer
rona pr -l bug -l urgent -r tomplanche

# Send a file written before, without the editor and without the prompt
rona pr --body-file PRs/my_feature.md -y

# Open the pre-filled web form instead of a CLI backend
rona pr --web

# Print the command that would run, and change nothing
rona pr --dry-run

Request document:

# [FEAT] Add the pr command

## Summary

- One Markdown file holds the whole request.
- The first heading is the title.

Rona sends [FEAT] Add the pr command as the title. The description starts at ## Summary.

`reset`

Unstage files (the inverse of add). This is non-destructive: working-tree edits are always preserved.

rona reset [FILES...] [-i] [--dry-run]

Options:

-i, --interactive - Pick which staged files to unstage from a checklist
--dry-run - Preview what files would be unstaged without modifying the index

Behavior:

With explicit FILES, only those files are unstaged
With no arguments, every staged file is unstaged (like git reset)
With -i, a MultiSelect of staged files is shown and only the selected ones are unstaged
Working-tree changes are never discarded; only the index is touched
In a repository with no commits yet, it falls back from git restore --staged to git rm --cached
With nothing staged, rona reset and rona reset -i print "No staged files to unstage."

Examples:

# Unstage everything currently staged (non-destructive)
rona reset

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

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

# Preview what would be unstaged without touching the index
rona reset --dry-run

Interactive mode (-i):

Each staged file is listed with a short status label (new file, modified, deleted, renamed, copied, type change):

> Select files to unstage
  [x] modified    src/cli.rs
  [ ] new file    notes.txt
Unstaged 1 files.

Use the arrow keys to move, space to toggle a file, and enter to confirm.

`restore`

Discard working-tree changes, reverting files to their staged (or HEAD) state. This is destructive, so a confirmation prompt is shown before anything is discarded unless -y/--yes or --dry-run is passed.

rona restore [FILES...] [-i] [-y | --yes] [--dry-run]

Options:

-i, --interactive - Pick which changed tracked files to discard from a checklist
-y, --yes - Skip the confirmation prompt
--dry-run - Preview what files would be discarded without changing anything (no prompt)

Behavior:

With explicit FILES, only those files are discarded (after confirmation)
With -i, a MultiSelect of changed tracked files is shown and only the selected ones are discarded
Running it with neither FILES nor -i is a deliberate no-op that prints a hint, since discarding every change at once is rarely intended
Untracked files are never touched (git cannot restore them)
Declining the confirmation prompt prints "Restore cancelled." and changes nothing

Examples:

# Discard changes to a file (prompts for confirmation first)
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

# Preview what would be discarded without changing anything
rona restore --dry-run src/main.rs

Interactive mode (-i):

Each changed tracked file is listed with a short status label (untracked files are excluded):

> Select files to restore
  [x] modified    src/cli.rs
  [ ] deleted     old_module.rs
? Discard working-tree changes to 1 file(s)? This cannot be undone. (y/N)
Restored 1 files.

`set-editor` (`-s`)

Set the default editor for commit messages.

rona set-editor <editor> [--dry-run]  # Any command-line editor (vim, zed, "code --wait", etc.)

Options:

--dry-run - Preview what would be changed without modifying config

Examples:

# Set editor to vim
rona set-editor vim

# Preview editor change
rona set-editor vim --dry-run

`sync`

Synchronize current branch with a source branch using merge or rebase strategy.

rona sync [OPTIONS]

Options:

-b, --branch <BRANCH> - Source branch to sync from (defaults to "main")
-r, --rebase - Use rebase instead of merge for synchronization
-n, --new-branch <NAME> - Create a new branch before syncing
--no-stash - Keep local changes in place instead of stashing them during the sync
--dry-run - Preview sync operations without making changes
-v, --verbose - Show detailed operation information

Behavior:

Stashes local changes to tracked files, if there are any, so the branch switch can go through
If --new-branch is specified, creates and switches to the new branch
Switches to the source branch (default: "main")
Pulls latest changes from remote
Switches back to the target branch
Merges (or rebases with -r) the source branch into the current branch
Restores the stashed changes, with the staged and unstaged split intact

Untracked files stay where they are: git carries them across a branch switch on its own. If any step fails, the changes stay in the stash and rona prints how to restore them.

Examples:

# Sync current branch with main (using merge)
rona sync

# Sync current branch with main (using rebase)
rona sync -r

# Sync from a different source branch
rona sync -b develop

# Sync from develop using rebase
rona sync -b develop -r

# Create a new branch and sync it with main
rona sync -n feature/new-work

# Create a new branch and sync with develop using rebase
rona sync -n feature/new-work -b develop -r

# Preview what would happen without making changes
rona sync --dry-run

# Fail on local changes instead of stashing them
rona sync --no-stash

# Verbose output showing all operations
rona sync -v

# Combine options for detailed preview
rona sync -b develop -r --dry-run -v

Use Cases:

Keep feature branches up to date with main/develop
Start new feature branches with latest changes
Maintain clean git history with rebase strategy
Safely preview branch operations before executing

`help` (`-h`)

Display help information.

rona help
# or
rona -h

Command Options

Global Options

These options can be used with any command, before or after the subcommand:

--version or -V: Display version information
--verbose or -v: Enable verbose output (shows detailed operation information)
-f, --config-file <PATH>: Load a specific TOML file instead of the default global/project hierarchy

Examples:

# Run any command with verbose output
rona -v -c -p

# Use a specific config file (flag can appear before or after the subcommand)
rona -f /path/to/custom.toml -g
rona branch -f .rona-release.toml

# Check version
rona --version

Commit Options (passed through to git)

When using rona -c [extra args], you can pass additional Git commit options:

--no-verify: Skip pre-commit hooks
--amend: Amend the previous commit
--no-edit: Use the previous commit message
--signoff: Add Signed-off-by line

Push Options (passed through to git)

When using rona -p [extra args], you can pass additional Git push options:

--force: Force push changes
--no-verify: Skip pre-push hooks
--tags: Push tags
--all: Push all branches

Command Combinations

Common Workflows

Quick Commit and Push:

rona -a "src/" -g -c -p

Interactive Commit:

rona -a "*.rs" -g -i -c

Auto-Confirmed Commit with Push:

rona -a "src/" -g -i -c -y -p

Commit with Clipboard Copy:

rona -c --copy  # Message copied to clipboard

Verbose Mode for Debugging:

rona -v -a "src/" -g -c -p

Custom Config Workflow:

rona -f ./team.toml -g -c -p

Force Push:

rona -c -p --force

Amend Commit:

rona -c --amend

CI/CD Workflow:

rona -v -a "*" -g -i -c -y -p --no-verify

Set up project config and hide it from git:

rona config -c local -e

Create a branch from a dedicated config:

rona -f .rona-release.toml branch

Branch, commit, push, and open the request:

rona branch
rona -a "src/" -g -c -p
rona pr

Configuration Files

commit_message.md: Commit message template (generated by rona -g)
pr_description.md: Pull/merge request document (generated by rona pr)
.commitignore: File patterns to ignore (generated by rona -g)
.rona.toml (project-level): Project-specific Rona configuration
~/.config/rona.toml (global): User-level Rona configuration
~/.config/rona/config.toml (legacy): Old config path (still supported for backward compatibility)

Configuration File Format

See the Configuration page for the complete reference, including all options, template variables, conditional blocks, and the extra fields system.

Configuration Precedence:

Project-level config (.rona.toml) — highest priority
Files pulled in by the project config's extends chain
Files pulled in by a matching [[overrides]] entry declared in a global config
Global config (~/.config/rona.toml)
Legacy global config (~/.config/rona/config.toml)
Built-in defaults — lowest priority

Next Steps

Check the Usage Guide for practical examples
Set up Shell Integration for your preferred shell
Visit the FAQ for common questions and answers

zoizo

Navigation Menu

Command Reference

Command Reference

Core Commands

`branch`

`add-with-exclude` (`-a`)

`commit` (`-c`)

`completion`

`config`

`config create` (`-c`)

`config which` (`-w`)

`generate` (`-g`)

`init` (`-i`)

`list-status` (`-l`)

`push` (`-p`)

`pr` (`mr`, `pull-request`)

`reset`

`restore`

`set-editor` (`-s`)

`sync`

`help` (`-h`)

Command Options

Global Options

Commit Options (passed through to git)

Push Options (passed through to git)

Command Combinations

Common Workflows

Configuration Files

Configuration File Format

Next Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Command Reference

Command Reference

Core Commands

branch

add-with-exclude (-a)

commit (-c)

completion

config

config create (-c)

config which (-w)

generate (-g)

init (-i)

list-status (-l)

push (-p)

pr (mr, pull-request)

reset

restore

set-editor (-s)

sync

help (-h)

Command Options

Global Options

Commit Options (passed through to git)

Push Options (passed through to git)

Command Combinations

Common Workflows

Configuration Files

Configuration File Format

Next Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`branch`

`add-with-exclude` (`-a`)

`commit` (`-c`)

`completion`

`config`

`config create` (`-c`)

`config which` (`-w`)

`generate` (`-g`)

`init` (`-i`)

`list-status` (`-l`)

`push` (`-p`)

`pr` (`mr`, `pull-request`)

`reset`

`restore`

`set-editor` (`-s`)

`sync`

`help` (`-h`)