Usage Guide - TomPlanche/rona GitHub Wiki

Usage Guide

This guide will help you get started with Rona and show you how to use its features effectively in your daily workflow.

Basic Workflow

1. Initialize Rona

First, 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

2. Stage Files

Use the -a flag to stage files while excluding specific patterns:

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

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

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

# Exclude files with specific patterns
rona -a "test_*.rs" "*.test.js"

3. Generate Commit Message

Create and edit your commit message:

# Generate commit message template (opens editor)
rona -g

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

This will:

  1. Open an interactive commit type selector
  2. Create/update commit_message.md
  3. Either open your configured editor (default) or prompt for simple input (-i)

4. Commit and Push

Commit your changes and push to the remote repository:

# Commit with the prepared message
rona -c

# Commit and push in one command
rona -c -p

# Commit with additional Git arguments
rona -c --no-verify

Advanced Usage

Working with Multiple Branches

# Create and switch to a new feature branch
git checkout -b feature/new-feature
rona -a "*.rs"
rona -g
rona -c -p

# Switch back to main and merge
git checkout main
git merge feature/new-feature

Handling Large Changes

# Stage specific directories
rona -a "src/" "tests/"

# Exclude test files while staging
rona -a "src/" -e "test_*.rs"

# Stage everything except specific patterns
rona -a "*" -e "*.log" "*.tmp"

Using with CI/CD

# In your CI pipeline
rona init
rona -a "*"
rona -g
rona -c -p --no-verify

Common Use Cases

Feature Development

# Start new feature
git checkout -b feature/new-feature
rona -a "src/" "tests/"
rona -g  # Select 'feat' type
rona -c -p

Bug Fixes

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

Code Cleanup

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

Testing

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

Quick Commits (Interactive Mode)

# Fast workflow without opening editor
rona -a "src/"
rona -g -i  # Select type and input message directly
rona -c -p

Best Practices

  1. Commit Messages

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

  2. File Staging

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

  3. Branch Management

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

  4. Workflow Integration

    • Set up shell completion
    • Configure your preferred editor
    • Use interactive mode for quick commits

Troubleshooting

Common Issues

  1. Editor Not Opening

    • Check if the editor is properly configured
    • Verify the editor is installed
    • Try using a different editor

  2. Pattern Exclusion Not Working

    • Verify pattern syntax
    • Check for typos
    • Ensure patterns are properly quoted

  3. Commit Message Issues

    • Check file permissions
    • Verify editor configuration
    • Try interactive mode

Next Steps