Skip to content

Features

Jump to bottom
Tom Planche edited this page Sep 4, 2026 · 14 revisions

Features

Rona comes with a rich set of features designed to enhance your Git workflow. Here's a comprehensive overview of what Rona offers.

Core Features

Intelligent File Staging

  • Pattern-based file exclusion
  • Support for multiple exclusion patterns
  • Directory-based staging
  • Smart file tracking
  • Interactive checklist staging (-i) as an additive alternative to exclusion
# Exclude Rust files
rona -a "*.rs"

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

# Exclude directories
rona -a "target/" "node_modules/"

# Pick files to stage from a checklist (git add -p / lazygit style)
rona -a -i

Safe Unstage and Discard

  • rona reset unstages files (the inverse of add), non-destructively: working-tree edits are always preserved
  • rona restore discards working-tree changes, reverting files to their staged (or HEAD) state
  • Both mirror the interactive add (-i) pattern with a MultiSelect checklist
  • restore is destructive, so it asks for confirmation before discarding (skip with -y)
  • Untracked files are never touched by restore (git cannot restore them)
# 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

# 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

Structured Commit Messages

  • Interactive commit type selection
  • Automatic file change tracking
  • Commit message templates
  • Support for conventional commits
  • Auto-detected GPG commit signing by default (can be disabled with --unsigned)
  • Auto-confirm commits with --yes flag
  • Copy commit message to clipboard with --copy flag
# Generate commit message template
rona -g

# Interactive mode
rona -g -i

# Commit with auto-confirmation
rona -c -y

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

Streamlined Push Operations

  • One-command commit and push
  • Branch management
  • Remote repository handling
  • Push verification
# Commit and push in one command
rona -c -p

# Push to specific branch
rona -c -p origin main

Branch Creation

  • Interactive branch name generation from a configurable template
  • Dedicated branch_types list (or merged from commit_types)
  • branch_extra_fields for project-specific branch prompts
  • branch_field_order to control prompt sequence
  • Prompts skipped automatically when not referenced in the template
  • prefetch.source = "branches" to populate selects from existing branch names
  • Dry-run mode and --no-switch option
# Interactive branch creation
rona branch

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

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

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

Branch Synchronization

  • Automated branch synchronization workflow
  • Support for both merge and rebase strategies
  • Pull latest changes from source branch
  • Create new branches before syncing
  • Local changes stashed and restored around the branch switch
  • Safe operations with dry-run mode
# Sync current branch with main
rona sync

# Sync using rebase instead of merge
rona sync -r

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

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

# Preview sync operations
rona sync --dry-run

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

Pull and Merge Requests

  • One Markdown document holds the whole request, title and description together
  • The first # Heading is the title
  • New documents start from the request template of the repository
  • Four backends: gh, glab, GitLab push options, and a pre-filled web form
  • Rona reads the forge from the remote URL and picks a backend from the binaries you have
  • Labels, reviewers, assignees, and draft state, from flags or from the config
  • Rona warns when a backend cannot carry a field instead of dropping it in silence
# Write the request in your editor, then open it
rona pr

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

# Add labels and a reviewer
rona pr -l bug -r alice

# Send a file written before
rona pr --body-file PRs/my_feature.md -y

# Open the pre-filled web form
rona pr --web

# Preview the command without opening anything
rona pr --dry-run

Interactive Commit Type Selection

  • Predefined commit types (defaults)
  • Custom commit type support via configuration
  • Type-based message templates
  • Commit type validation

Default commit types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • test: Adding or modifying tests
  • chore: Maintenance tasks

Additional types (such as style, refactor) can be enabled by configuring them in .rona.toml or ~/.config/rona.toml.

Template Configuration

  • Customizable commit message templates
  • Support for multiple template variables
  • Flexible formatting options
  • Per-project or global templates

Available template variables:

  • {commit_number} - Incremental commit number
  • {commit_type} - Selected commit type (feat, fix, etc.)
  • {branch_name} - Current branch name
  • {message} - Your commit message
  • {date} - Current date (YYYY-MM-DD)
  • {time} - Current time (HH:MM:SS)
  • {author} - Git author name
  • {email} - Git author email
  • {name} - Any extra field defined under [[extra_fields]] (e.g. {scope}, {ticket})

Conditional blocks:

  • {?variable}content{/variable} - Content renders only when variable is non-empty
  • Prevents empty brackets or placeholder text for optional variables
  • Example: {?commit_number}[{commit_number}] {/commit_number} renders [5] when commit_number exists, or nothing when using -n flag

Example templates:

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

# Conventional commits with optional scope and ticket
template = "{commit_type}{?scope}({scope}){/scope}: {message}{?ticket} [{ticket}]{/ticket}"

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

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

# With author info
template = "{commit_type}: {message} by {author}"

Extra Fields

Declare additional prompts in .rona.toml under [[extra_fields]]. Each field becomes a template variable using its name. This replaces the need for a project-specific fork when you need structured inputs such as a component scope or a ticket reference.

Field options:

Key Type Default Description
name string required Variable name used in the template
prompt string name Label shown to the user
kind "text" / "select" "text" Input style
required bool false Reject empty answers
validation string — Regex the answer must match
prefetch.source "command" / "branch" / "branches" — Where to fetch candidate values
prefetch.command string — Shell command whose output is parsed ("command" source only)
prefetch.extract_regex string — Regex per output line or branch name. Priority: named group value, capture group 1, full match
prefetch.deduplicate bool false Remove duplicate results ("command" and "branches" sources)

Prompt behaviour:

kind Prefetch result Behaviour
select non-empty list Select list + (none) (if optional) + Other (enter manually)
select empty Falls back to free-text
text non-empty list from command or branches Same as select with non-empty list
text 0–1 values from branch Free-text with extracted value as default
text nothing Plain free-text

Example — conventional commits with scope and ticket:

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]+"

Configurable Prompt Order

By default prompts appear as: extra fields (in declaration order), then the message. Use field_order to change this. The reserved name "message" positions the built-in message prompt; any extra field not listed is appended at the end.

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

Multi-Shell Completion

  • Bash completion
  • Fish shell completion
  • Zsh completion
  • PowerShell completion
  • Context-aware suggestions
  • Command and flag completion

Advanced Features

Git Integration

  • Seamless Git command integration
  • Git status tracking
  • Branch management
  • Remote repository handling

Configuration Management

  • Easy configuration file creation with config command
  • Support for both local (.rona.toml) and global (~/.config/rona.toml) configuration
  • Configuration file discovery with config which subcommand
  • Display effective configuration values
  • Custom editor support
  • Custom commit types
  • Template configuration
  • Project-level and global settings
  • Shared base configs via extends, and directory-scoped configs via [[overrides]]
  • Backward compatibility with old config paths
  • Automatic directory creation for configuration files
# Create local project config
rona config create local

# Create global user config
rona config create global

# Check which config file is being used
rona config which

# Show effective configuration values
rona config which --effective

Development Tools

  • Verbose mode (-v flag) for detailed operation tracking
  • Dry-run mode (--dry-run) for previewing operations
  • Configuration debugging with config which
  • Effective configuration value inspection
  • Custom configuration file support
  • Comprehensive error handling
  • Auto-confirmation mode for CI/CD (--yes flag)
# Verbose mode for debugging
rona -v -c -p

# Dry-run to preview operations
rona -c --dry-run

# Check active configuration
rona config which --effective

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

Use Cases

Feature Development

rona branch          # Select 'feat' type
rona -a "src/" "tests/"
rona -g              # Select 'feat' type
rona -c -p
rona pr              # Open the pull request

Bug Fixes

git checkout -b fix/bug-description
rona -a "src/"
rona -g  # Select 'fix' type
rona -c -p

Code Cleanup

git checkout -b chore/cleanup
rona -a "src/" -e "*.rs"
rona -g  # Select 'chore' type
rona -c -p

Testing

git checkout -b test/add-tests
rona -a "tests/"
rona -g  # Select 'test' type
rona -c -p

Next Steps

zoizo

Clone this wiki locally