perch

A real-time terminal dashboard for git changes. Watch your working tree update live as you edit files, with PR status and a one-keystroke in-app diff overlay.

Overview

Run perch in a terminal pane alongside your editor. It shows a live-updating list of changed files with insertion/deletion counts and — when the current branch has a PR open on GitHub — a compact PR status strip with review, check, and mergeability state. Press m to cycle between the normal status-grouped view, a condensed flat file list, and a tree view that groups changes by directory. Press Enter (or d / Space / l / →) on a file to open its full diff in a centered in-app overlay, or use those same keys to toggle directories in tree mode. Updates are event-driven via filesystem watches; there is no polling of the working tree.

Install

Homebrew (macOS / Linux)

brew install upsertco/perch/perch

From source

cargo install --path .

Or see Development for a Nix-based setup.

Usage

# Current directory
perch

# Specific repo
perch /path/to/repo

# Custom debounce
perch --debounce 500

perch can be launched from any directory inside a git working tree — the repository root is discovered automatically.

CLI flags

Flag	Purpose
[PATH]	Repository path (default .)
-c, --config <FILE>	Path to config file
-d, --debounce <MS>	Filesystem debounce in ms (default 500)
--base <BRANCH>	Base branch for the branch-scoped diff range
--no-pr	Disable the GitHub PR status strip
--view <MODE>	Startup view: normal, condensed, tree
--no-flash	Disable the row flash on change
--flash-duration <MS>	Flash duration in ms
--scroll-padding <N>	Rows kept visible above/below the selection
--edit-command <CMD>	Editor command for the e key
--log <LEVEL>	Logging level: trace, debug, info, warn, error

Any flag that mirrors a config setting overrides the config file. Precedence is CLI flag > config file > built-in default.

Keybindings

Key	Action
j / ↓	Select next file
k / ↑	Select previous file
m	Cycle view mode (normal / condensed / tree)
Enter / l / → / Space / d	Open diff for files, toggle directories in tree mode
r	Refresh
?	Show the help popup
q / Ctrl+C	Quit

Inside the diff overlay:

Key	Action
j / ↓	Scroll down
k / ↑	Scroll up
Esc / q / h / ←	Close overlay
d / Space	Toggle overlay

Pressing a diff key opens a centered panel (~85% of the terminal) that renders the file's diff inline — colored +/-/context lines with line numbers, scrollable with j / k. The overlay lives inside the TUI (no external tool is invoked) and dismisses with Esc / q / h / ← (or toggles with d / Space).

Configuration

Config lives at ~/.config/perch/config.toml. All sections are optional; defaults are used for anything you omit.

Top-level

debounce_ms = 500            # filesystem event debounce in ms
base_branch = "main"         # optional override for branch-scoped diff base

When base_branch is omitted, perch resolves the base through four tiers: the branch's reflog fork point (recorded by git branch <name> <start> or git worktree add -b <name> <start>), the main worktree's HEAD branch, then origin/HEAD. All tiers read recorded git facts — perch never guesses main or master by name. If no tier resolves, Condensed and Tree views fall back to working-tree status and Normal hides the Committed group.

[display]

[display]
default_view = "normal"      # startup view: normal | condensed | tree
flash_on_change = true       # flash a file row when it changes
flash_duration_ms = 600      # flash duration
scroll_padding = 3           # rows kept visible around the selection (0 disables)

[pr]

Controls the compact PR status strip that appears when the current branch has an open PR on GitHub.

[pr]
enabled = true

The GitHub token is discovered from the GITHUB_TOKEN environment variable or your git config. If no token is available the PR strip silently stays hidden.

Full example

debounce_ms = 500
base_branch = "main"

[display]
default_view = "normal"
flash_on_change = true
flash_duration_ms = 600
scroll_padding = 3

[pr]
enabled = true

Colors

perch renders with the terminal's own 16-color ANSI palette, so it automatically matches whatever color scheme your terminal uses. There is no theme configuration — to change perch's colors, change your terminal's palette.

Development

Prerequisites

• Rust (pinned via rust-toolchain.toml)
• Or Nix + direnv for a reproducible dev environment

With Nix (recommended)

direnv allow  # one-time setup, auto-activates on cd
cargo run     # run the app
cargo test    # run tests

Without Nix

rustup show           # installs toolchain from rust-toolchain.toml
cargo run             # run the app
cargo test            # run tests
cargo clippy          # lint
cargo fmt             # format

Dev install (run your local build as perch)

cargo dev-install                 # build debug + symlink into ~/.local/bin
cargo run -p xtask -- uninstall   # remove the symlink

This symlinks target/debug/perch into ~/.local/bin/perch, so every later cargo build is instantly live. It does not touch a Homebrew-installed perch (that lives in the brew prefix); which one runs depends on PATH order — the command warns if ~/.local/bin is missing from PATH or shadowed.

Nix commands

nix flake check       # build + clippy + fmt
nix build             # build the package (output in ./result)
nix run               # build and run
nix flake update      # update pinned dependencies

License

MIT