🐸 rbt - Rebase Toolkit

A Terminal User Interface (TUI) tool for managing downstream forks and keeping them synchronized with actively-maintained upstream repositories.

What is rbt?

rbt helps teams maintain downstream forks by tracking which patches need to be carried forward during rebases. It provides a visual interface to see which downstream commits are present or missing on your current rebase branch, making it easier to ensure all necessary patches are applied.

Features

• Visual Commit Tracking: See all downstream patches and their status at a glance
• Commit Categorization: Automatically identifies carry, drop, and pending upstream commits
• Rebase Assistant: Track which commits are present or missing on your rebase branch
• Configurable: Customize upstream and downstream branch names
• In-Progress Rebase Updater: Helps you bring a currently in-progress rebase up to date with new revisions of upstream tags or downstream branches

AI Disclaimer

This tool attempts to codifiy preexisting processes and disparate scripts into one package. AI was involved in doing so, especially with regards to TUI/display logic. You have been appropriately warned.

Commit Prefix Convention

rbt recognizes commits in your downstream fork that follow these prefixes:

• UPSTREAM: <carry>: - Patches that should be carried forward indefinitely. These are downstream-specific changes that won't be adopted upstream.

  Example: UPSTREAM: <carry>: Add custom authentication middleware

• UPSTREAM: <drop>: - Commits that should not be carried forward. Typically used for generated files that will be regenerated later.

  Example: UPSTREAM: <drop>: Update generated API documentation

• UPSTREAM: 12345: - Pull requests opened upstream but not yet merged. The number represents the upstream PR number on GitHub.

  Example: UPSTREAM: 12345: Fix memory leak in connection pool

When a PR is merged upstream, you can drop the corresponding downstream commit since it will come in through the upstream sync.

Getting Started

Prerequisites

• Go 1.21 or later

Installation

1. Clone the repository:

git clone <repository-url>
cd rbt

2. Build the application:

make build

3. (Optional) Install globally:

make install

Running

Run the application from the project directory:

./rbt

Or if installed globally:

rbt

Configuration

Create a .rbt file in your repository root:

cp .rbt.example .rbt

Edit .rbt to configure your upstream and downstream branches:

git:
  upstream_branch: "upstream-master"    # Your upstream remote branch
  downstream_branch: "downstream-master" # Your downstream master branch

Note: rbt automatically detects the most recent merge commit using git log HEAD ^downstream-master --merges --oneline to use as the base for presence checking. This ensures commits are only considered PRESENT if they exist after your most recent rebase/merge.

You can also specify a custom configuration file location:

rbt --config /path/to/config.yaml

Workflow

1. Start from the upstream branch you'd like to rebase from:

   git checkout v1.35

2. Create a rebase branch:

   git checkout -b rebase-1.35

3. Use the "ours" strategy to create a merge commit:

   git merge -s ours downstream-master

4. Run rbt to see commit status:

   rbt

5. View shows two columns:

   • Left: Commits with UPSTREAM: prefix from downstream and current branch
   • Right: Status indicating commit state:
     • ✓ PRESENT - Commit from downstream is on current branch
     • ✗ MISSING - Commit from downstream is NOT on current branch
     • + NEW - Commit on current branch that wasn't in downstream

6. Compare commits side-by-side:

   • Press Enter on any PRESENT commit to open a comparison view
   • See the commit from downstream on the LEFT and current branch on the RIGHT
   • Verify your rebased version matches or improves upon the downstream version
   • Both sides scroll together to keep comparisons aligned

7. Cherry-pick or apply missing commits as needed during your rebase process.

The tool helps you ensure all necessary downstream patches are applied to your rebase branch, and shows you any new UPSTREAM commits you've added.

Update Rebase

The update rebase feature helps you bring a currently in-progress rebase up to date with new revisions of upstream tags or downstream branches. This is useful when:

• A new upstream version/tag is released while you're working on a rebase
• Your downstream branch has been updated with new patches
• You want to rebase your work onto a newer base

How It Works

Press u in the commit list view to open the update rebase form, which will:

1. Collect all UPSTREAM commits from your current branch
2. Switch to a new upstream tag (e.g., a newer version)
3. Create a new rebase branch from that tag
4. Merge your downstream branch using the "ours" strategy to establish ancestry
5. Cherry-pick all UPSTREAM commits from your current branch onto the new base

Usage

1. From the commit list, press u to open the update rebase form

2. Fill in the form:

   • New branch name: Name for your updated rebase branch (e.g., rebase-v2.1.0)
   • Upstream tag: The new upstream version to rebase onto (e.g., v2.1.0)
   • Downstream branch: The downstream branch to merge for ancestry (typically your configured downstream branch)

3. Press Enter to start the automated rebase process

4. Monitor progress: The progress view shows:

   • Current phase of the rebase
   • Progress bar for cherry-picking commits
   • Recent activity log
   • Any conflicts that need resolution

5. Handle conflicts: If a cherry-pick conflict occurs:

   • The rebase pauses automatically
   • Resolve conflicts in your editor
   • Press Enter to continue
   • The rebase resumes from where it paused

Rebase State Tracking

The update rebase process creates a state file (.rbt-rebase-<branch-name>.json) that tracks:

• Which commits have been cherry-picked
• Which commits had conflicts that were resolved
• Current progress through the commit list

Key Bindings

Commit List View

• q, Ctrl+C: Quit the application
• ?, h: Show help
• ↑/↓ or j/k: Navigate commit list
• g / G: Jump to top / bottom of list
• Enter: Compare commit
• u: Open update rebase form
• r: Refresh commit status

Comparison View

• ↑/↓ or j/k: Scroll both sides together
• g / G: Jump to top / bottom
• PgUp / PgDn: Page up / down
• Esc or q: Return to commit list

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

Apache 2.0