herdr-gitview

features · install · quick start · configuration · limitations · changelog

A git view for herdr. Changed files on one side, a syntax-highlighted diff on the other. Press Enter and the diff pane becomes your real nvim - opened at the first changed line. You never leave the terminal.

Inspired by herdr-reviewr, rebuilt around a real editor - edit diffs in place with full nvim + LSP support, not just view them.

herdr-gitview-1.mp4

Features

• Grouped changes - conflicts, staged, and unstaged changes in separate sections. s moves a file between staged and unstaged.

• Readable diffs - syntax highlighting, word-level emphasis on edited lines, and collapsible context folds you expand with a click.

• Edit in real nvim - Enter turns the diff pane into your actual nvim: full LSP, plugins, colors. Edit the file right there at the changed line, :wq, and the diff refreshes. No embedded-terminal emulation - it runs on the pane's own PTY.

• Stage, discard, commit inline - the commit message opens in nvim too; discards confirm first. s/u/x work on a directory row too, applying to every file under it in that section.

• Commit history - l opens a git log view; pick a commit to browse its files and per-commit diffs. w filters it to just the commits your branch added on top of its base (and opening the log from branch scope starts there).

• Knows what your branch was cut from - branch scope diffs against the branch you actually branched off, so a branch stacked on another feature branch shows only its own work instead of both.

• Review notes to any agent - select diff lines, annotate, and send the batch into the input of any agent pane you pick in the workspace. It types; you decide when to press enter. You write a note inline in the diff, in a box under the lines it comments on, and it stays there as a card once saved. The composer is a wrapping text area: shift+enter (or ctrl+j) for a new line, arrows/home/end to move around, ctrl+w to drop a word, esc to cancel.

• Always says which diff you are looking at - the header names the comparison first, before the branch: uncommitted · feat/x or vs origin/next · feat/x · 3 commits. The diff pane says the same thing, and the footer's w hint names the view it switches to. On a narrow pane the file counts go before the comparison does.

• Mouse support - click to select, double-click to open, drag-select diff lines, wheel to scroll, click folds to expand.

Requirements

• herdr ≥ 0.7.0 (≥ 0.7.4 for the native floating dialogs; older versions fall back to in-pane overlays).
• git on PATH.
• nvim for the editor loop (any editor works via config; the remote-control niceties - file switching, save/discard prompts - are nvim-only).
• A truecolor terminal. Pick the theme matching its background (Theme).
• macOS or Linux.

Install

Prebuilt binaries, no Rust toolchain needed:

herdr plugin install ChmaraX/herdr-gitview

Bind a key in ~/.config/herdr/config.toml (cmd+g is free of herdr's defaults; any key works):

[[keys.command]]
key = "cmd+shift+g"
type = "plugin_action"
command = "chmarax.gitview.toggle"   # sidebar in the current tab
description = "git view sidebar"

[[keys.command]]
key = "cmd+g"
type = "plugin_action"
command = "chmarax.gitview.toggle-tab"   # dedicated gitview tab
description = "git view tab"

toggle opens a sidebar in the tab you're in (each tab can have its own); press again in that tab to close. toggle-tab opens one dedicated tab per repo and jumps to it if it's already open.

To update, reinstall - your config survives:

herdr plugin uninstall chmarax.gitview && herdr plugin install ChmaraX/herdr-gitview

Without herdr, the file list runs as a plain terminal app in any repo - browse, stage, unstage, discard:

herdr-gitview list

Editing, commits, history diffs, and notes need the second pane, i.e. herdr.

Quick start

1. Open it. cmd+g in any repo. Changed files on the right, the selected file's diff on the left.
2. Browse. j/k (or the wheel) - the diff follows your cursor. Tab-free: selecting a file under staged changes shows its staged diff, under changes the unstaged one.
3. Edit. Enter - nvim opens in the diff pane at the first changed line. :wq, and you're back on the refreshed diff, focus on the list.
4. Stage & commit. s to stage (the file moves up), x to discard (asks first), c to commit - write the message in nvim, :wq commits, :q! aborts. On a directory row the same keys apply to the whole folder.
5. See what your branch did. w switches the file list to "vs the base branch"; l then opens the log already filtered to your branch's commits (w toggles that filter in the log view too).
6. Review for your agent. Focus the diff pane, v + j/k (or drag) to select lines, a to annotate - a box opens right under the selection, type and enter. Notes stay as cards under the code. p → pick an agent → the batch lands in its input.

The footer in each pane shows only the keys that currently work, so you learn it by using it.

Branch scope

w switches the file list from the working tree to "everything this branch changed". The base it compares against is the branch this one was created from, not a fixed trunk: a branch cut from develop diffs against develop, and a branch stacked on another feature branch diffs against that branch. The header names it, e.g. nv-2-ui vs nv-1-api.

It works by ancestry, not by naming: every other branch is ranked by how recently your branch diverged from it, and the nearest one wins. Ties between siblings cut from the same commit go to the trunk. On a trunk itself there is nothing to be cut from, so the usual origin/HEAD → origin/main → origin/master → main → master chain applies.

One case it can get wrong: a branch created from yours also has a recent divergence point. Branches containing all of your commits are ignored, which covers the usual shape, but if the guess is ever wrong, pin it:

base = "origin/main"

Configuration

$HERDR_PLUGIN_CONFIG_DIR/config.toml, usually ~/.config/herdr/plugins/config/chmarax.gitview/config.toml. Every key is optional; assets/example-config.toml shows all defaults, commented.

Key	Default	Meaning
theme	"dark"	"dark" or "light" - syntax theme + all UI tints
editor	["nvim"]	Editor argv; the file (and +<line>) is appended
base	""	Branch-scope base ref; "" detects the branch this one was cut from (see Branch scope)
list_side	"right"	"right" or "left"
view_width_percent	50	Sidebar mode: how much of the tab gitview takes; your existing panes get the rest (20–80)
list_width_percent	25	How much of the gitview area the file list takes (10–80)
default_scope	"worktree"	"worktree" or "branch" - which scope the view opens in
context_lines	3	Unchanged lines kept around each change before folding (0–20)
poll_ms	2000	Auto-refresh interval in ms; 0 disables, non-zero floored at 250
show_untracked	true	Include untracked files

Theme

theme = "dark" pairs a dark syntax palette with dark red/green diff tints; "light" is GitHub-web-flavored. Match your terminal's background - diff tints are painted as real background colors.

Keybindings

[keybindings] maps action names to keys. An override replaces all default keys for that action; binding a key another action owns is reported at startup and the table is ignored until fixed.

[keybindings]
stage = "space"
discard = "ctrl+x"

Grammar: [ctrl+][alt+][shift+]<key> where <key> is a single character or enter, esc, tab, space, up, down, left, right, pgup, pgdn, home, end. Action names: down up top bottom edit stage unstage discard commit log annotate select send_notes notes_view delete toggle_scope refresh help quit half_page_down half_page_up diff_top diff_bottom scroll_down scroll_up.

Limitations

• Editing needs herdr - standalone herdr-gitview list covers browsing and staging only.
• Remote editor tricks need nvim (--listen/--server). Other editors work for plain editing; you close them yourself.
• Notes live in memory - closing the view discards unsent notes.
• Notes attach to working-tree changes - you can't annotate historical commits.
• Native floating dialogs need herdr ≥ 0.7.4; older versions get in-pane overlays.

Building from source

git clone https://github.com/ChmaraX/herdr-gitview
cd herdr-gitview
cargo build --release
herdr plugin link "$PWD"

cargo test runs the full suite - parser units, fixture git repos, and ratatui render tests. just release-dry mirrors CI (fmt, clippy, tests, release build). GITVIEW_DEBUG=1 writes a debug log to the plugin state dir.

Attribution

The structured diff renderer and highlighting approach are ported, in simplified form, from herdr-reviewr (MIT).

License

MIT