branchdiff 0.59.1

Terminal UI showing unified diff of current branch vs its base
Documentation

branchdiff

Terminal UI showing unified diff of current branch vs its base.

Features

  • Git and Jujutsu (jj) support with automatic backend detection
  • Auto-switching: detects jj init or .jj removal at runtime and seamlessly restarts
  • Color-coded diff view with distinct colors per change layer (git: committed/staged/unstaged; jj: earlier/current/later commits)
  • Inline diff highlighting showing exactly which characters changed
  • Multiple view modes: context (default), changes-only, full file, and jj-specific commit-only and bookmark-only modes
  • Image diffs with side-by-side before/after panels
  • Live file watching with auto-refresh on changes
  • Mouse support: scrolling, click-to-collapse file sections, text selection with auto-copy (double-click word, triple-click line)
  • Copy to clipboard: auto-copy on selection, file path, entire diff, or git patch format
  • Non-interactive output modes for scripting (--print, --diff)

Requirements

  • Git: Any reasonably modern git (1.7+). Conflict detection requires Git 2.38+.
  • Jujutsu (optional): If a .jj directory is present, branchdiff uses jj automatically. When remote tracking bookmarks exist (e.g. main@origin), branchdiff shows the full stack diff from trunk() to @, with earlier stack commits in teal and the current commit's changes in green. Falls back to @- vs @ when no remote is configured.

Installation

Homebrew (macOS/Linux)

brew tap michaeldhopkins/tap
brew install branchdiff

Shell installer (macOS/Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/michaeldhopkins/branchdiff/releases/latest/download/branchdiff-installer.sh | sh

From source

cargo install --git https://github.com/michaeldhopkins/branchdiff

Manual download

Download binaries from GitHub Releases.

Usage

branchdiff [path]

If no repository is found, branchdiff waits and automatically starts when git init or jj init is detected.

Options

Flag Description
-p, --print Print diff to stdout and exit (non-interactive mode)
-d, --diff Output unified patch format to stdout (for git apply / patch)
--no-auto-fetch Disable automatic fetching of base branch
--benchmark N Run stress test rendering N frames (for profiling)
-h, --help Print help
-V, --version Print version

Profiling

The --benchmark flag runs a non-interactive stress test for profiling:

# Run 1000 frames of simulated usage
branchdiff --benchmark 1000

# Generate a profiling report with source attribution
./scripts/profile.py --frames 5000

# Or profile interactively with samply
cargo install samply
samply record ./target/profiling/branchdiff --benchmark 5000

The profiling script categorizes functions by source (branchdiff, ratatui, std, system) to help identify what's worth optimizing vs accepting from dependencies.

The benchmark simulates scrolling, file navigation, and view mode changes while rendering each frame.

Keybindings

Key Action
j / k Next / previous file
↓ / ↑ Scroll line
Ctrl+d / PgDn Page down
Ctrl+u / PgUp Page up
g / Home Go to top
G / End Go to bottom
c Cycle view mode (context → changes → full; jj adds commit → bookmark)
r Refresh
p Copy current file path
Y Copy entire diff
D Copy git patch format
? Toggle help
q / Esc / Ctrl+c Quit

Mouse

  • Scroll wheel to scroll
  • Click file headers to collapse/expand
  • Click and drag to select text (auto-copies to clipboard on release)
  • Double-click to select word, triple-click to select line (auto-copies to clipboard)

Contributing

Requirements

  • Rust 1.91+ (edition 2024)

Build and test

git clone https://github.com/michaeldhopkins/branchdiff
cd branchdiff
cargo build
cargo test

Install local build

After making changes, install the binary locally:

cargo install --path .

Before committing

Run clippy with warnings as errors (required by CI):

cargo clippy -- -D warnings

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Copyright (c) 2025-2026 Michael Hopkins.