Usage Guide

Usage Guide

Basic Workflow

1. Stage files:

rona -a "*.rs" "*.log"      # Exclude patterns
rona -a -i                   # Pick files from a checklist

2. Generate commit message:

rona -g                      # Opens editor
rona -g -i                   # Interactive mode
rona -g -n                   # Without commit number

3. Commit and push:

rona -c                      # Commit
rona -c -p                   # Commit and push
rona -c -y                   # Skip confirmation
rona -c -u                   # Unsigned commit

4. Open the pull request:

rona pr                      # Write the request, then open it
rona pr --draft              # Open it as a draft

Undoing Changes

Unstage files (non-destructive, working-tree edits are kept):

rona reset                   # Unstage everything (like git reset)
rona reset src/main.rs       # Unstage a single file
rona reset -i                # Pick staged files from a checklist

Discard working-tree changes (destructive, prompts for confirmation):

rona restore src/main.rs     # Discard a file's changes
rona restore -i              # Pick changed files from a checklist
rona restore -y src/main.rs  # Skip the confirmation prompt

Untracked files are never touched by restore.

Branch Creation

rona branch                  # Interactive branch name generation
rona branch --dry-run        # Preview without creating
rona branch --no-switch      # Create without switching
rona -f .rona-release.toml branch  # Use a dedicated config

Configure in .rona.toml:

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

[[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

Session (rona branch):

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

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

Branch Sync

rona sync                    # Merge from main
rona sync -r                 # Rebase instead
rona sync -b develop         # From different branch
rona sync -n feature/new     # Create new branch

Pull and Merge Requests

rona pr                      # Write the request in your editor, then open it
rona pr --draft -t develop   # Draft, against develop
rona pr -l bug -r alice      # Add a label and a reviewer
rona pr -b PRs/feature.md -y # Send a file written before
rona pr --web                # Open the pre-filled web form
rona pr --dry-run            # Preview without opening anything

Rona writes the request to pr_description.md and opens your editor. The first # Heading is the title. Everything below it is the description.

# [FEAT] Add the pr command

## Summary

- One Markdown file holds the whole request.

The file starts from the request template of the repository, under .github/ or .gitlab/. Rona pushes the branch, then opens the request with gh, glab, GitLab push options, or a web form, depending on the remote and on the binaries you have.

The aliases rona mr and rona pull-request run the same command.

Configuration

Rona reads .rona.toml (project) and ~/.config/rona.toml (global). Project settings take precedence.

A global [[overrides]] entry can apply an extra config to every repository under a given directory, without those repositories needing their own .rona.toml:

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

Run rona config -w to see exactly which files are loaded from the current directory.

See the Configuration page for the full reference — editor, commit types, templates, extra fields, prompt ordering, extends, and [[overrides]].

Extra Fields

Add project-specific prompts (scope, ticket, etc.) via [[extra_fields]].

# .rona.toml — place template and other top-level keys BEFORE [[extra_fields]]
template = "{commit_type}{?scope}({scope}){/scope}: {message}{?ticket} [{ticket}]{/ticket}"

[[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

[[extra_fields]]
name = "ticket"
kind = "text"
validation = "^[A-Z]+-[0-9]+$"
prefetch.source = "branch"
prefetch.extract_regex = "[A-Z]+-[0-9]+"

Control the prompt sequence with field_order:

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

Session (rona -g -i on branch feat/PROJ-42_add-login):

> Select commit type   feat
> Message              Add login endpoint
> Select scope         api
> Ticket (PROJ-42)     PROJ-42

Result: feat(api): Add login endpoint [PROJ-42]

Common Examples

Feature:

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

Bug fix:

rona -a "src/" -e "test_*.rs"
rona -g
rona -c -p

Quick commit:

rona -a "*" && rona -g -i && rona -c -y -p