hunk

command module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 13, 2026 License: MIT Imports: 10 Imported by: 0

README

hunk

Your AI's code might be ugly. The diff won't be.

A standalone, themeable diff viewer for the terminal. Side-by-side, word-level highlighting, keyboard-driven — and when you run it inside a git repository, it turns into a live review pass you can stage from, hunk by hunk, or a read-only walk back through the commit history.

Built for the diffs coding agents produce: large, spread across many files, and miserable to read as raw git diff output.

image

Install

curl -fsSL https://raw.githubusercontent.com/wmarquardt/hunk/main/install.sh | sh

That drops the binary in ~/.local/bin. Set HUNK_INSTALL_DIR to put it somewhere else, or HUNK_VERSION to pin a release.

With Go:

go install github.com/wmarquardt/hunk@latest

Or build from a clone:

git clone https://github.com/wmarquardt/hunk
cd hunk
go build -o hunk .

Single static binary, no runtime dependencies. Git is only needed for the working-tree review and hunk log modes; reading a diff and diffing files or directories work without it.

Usage

hunk                     # review the working tree, and stage what you approve
hunk log                 # walk back through the commit history, read only
hunk log internal/ui     # only the commits that touch those paths
git diff | hunk          # read a diff from stdin
git show <sha> | hunk    # or any other diff-producing command
hunk old.txt new.txt     # diff two files, no git required
hunk old/ new/           # diff two directories

Output that is piped or redirected is passed through as plain unified diff, so hunk a b > patch.diff does what you would expect.

Options

Every flag picks the state hunk opens in; the matching key still toggles it during the session.

Flag Key Does
--theme <ref> theme name, path, or github.com/user/repo/name (also HUNK_THEME)
--theme-update re-download remote themes instead of using the cache
-u, --unified s open unified instead of side-by-side
--no-sidebar b open with the file sidebar hidden
--show-whitespace W render tabs and trailing spaces as visible marks
--no-syntax H open with syntax highlighting off
--filter <regex> F hide hunks whose every changed line matches
-w, --ignore-whitespace i hide whitespace-only changes (git modes)
-U, --context <n> + / - unchanged lines around each hunk (default 3)
--no-follow f open with live-follow paused (review mode)
-n, --max-count <n> commits to read, hunk log only (default 50)

Keys

Key Action
j / k, ↑ / ↓ scroll a line
ctrl-d / ctrl-u scroll half a page
n / p next / previous hunk
] / [ next / previous file
g / G top / bottom
/ search the diff; n / N repeat, esc clears
W show / hide whitespace (tabs, trailing spaces)
H toggle syntax highlighting
F filter out hunks matching a regex; empty clears
h / l, ← / → scroll sideways
s toggle side-by-side / unified
b toggle the file sidebar
? help
q quit
mouse click a file, a row, or a status-bar option; the wheel scrolls

In hunk log you also get } / { to move between commits. In working-tree review mode you get:

Key Action
space mark this hunk and move to the next one in the file
a / d mark / unmark, then jump to the next hunk
A / D mark / unmark every hunk in this file
w stage what is marked
u undo the last stage
f pause / resume following the working tree
i ignore / show whitespace-only changes
+ / - more / less context around each hunk

Marking is git add -p without the one-hunk-at-a-time straitjacket: see the whole change, jump around, mark as you go, then write it all at once.

The sidebar says where every file stands: · untouched, ◐ some hunks marked, ● all of them, ✓ already staged (gray when only part of it is). Untracked files are shown as all-additions and staged whole, and a file you stage fully stays on screen with its check instead of vanishing mid-review.

History

hunk log is git log -p you can walk around in. The sidebar splits in two — the commits on top, the files of the selected commit below — so the keys nest the way the history does:

Key Action
} / { older / newer commit
] / [ next / previous file in that commit
n / p next / previous hunk in that file
hunk log                 # the last 50 commits
hunk log -n 200          # more of them
hunk log README.md       # only the commits that touch a path

Everything that only looks at the diff still works — search, the regex filter, whitespace, syntax highlighting, side-by-side, + / - context, i. Nothing that writes does: marking, staging, undo and follow are not bound at all, and hunk log has no code path that can reach the index.

Merge commits show their diff against the first parent, so a merge is not a blank screen.

Every run of changed lines is wrapped in a rounded outline that crosses from one pane into the other, with an arrow on the seam pointing the way the change goes. Each pane closes on its own last changed line and the rule turns down into the taller pane's wall, so one line becoming four draws one shape narrowing rather than two boxes side by side — the outline itself shows the shape of the change. Inside a line, the words that actually changed are painted a shade stronger.

hunk follows the working tree while it is open: edits made by you, your editor, or an agent show up on their own, and marks on untouched hunks survive the reload. f pauses and resumes following. Because of that, opening hunk in a clean repository is fine — it waits, and fills in with the first change.

Staging runs git apply --cached, so it only ever writes the index — no working-tree file is created, modified, or deleted by hunk. If you stage something you did not mean to, git restore --staged . puts it back.

The side-by-side layout falls back to unified on narrow terminals, and the sidebar hides itself when there is no room for it.

Theming

hunk ships with two themes: hunk-dark (the default) and paper (light).

hunk --theme paper
HUNK_THEME=paper hunk

Writing your own

Themes are TOML files in ~/.config/hunk/themes/ ($XDG_CONFIG_HOME is honoured). A file named midnight.toml there is available as --theme midnight.

Every key is optional. Anything you leave out keeps the default theme's value, so a two-line theme is a perfectly good theme. One key does a lot of work: ui.accent is every highlight hunk draws — the @@ line, the current hunk, a change block's outline and its arrow, the status bar, the selected file — so recoloring the highlight is a one-line edit:

# ~/.config/hunk/themes/midnight.toml
name = "midnight"

[ui]
accent = "#7aa2f7"

[diff]
added_fg   = "#7ee787"
removed_fg = "#ff7b72"

The full schema, with every key and what it colors, is in internal/theme/builtin/hunk-dark.toml — copy it and edit. Values are hex colors (#rgb or #rrggbb). A typo'd key gets a warning, a bad color gets an error naming the key, and neither costs you your diff: hunk falls back to the default theme and carries on.

Themes from GitHub

Reference a theme the way Go references a module:

hunk --theme github.com/someone/hunk-themes/dracula
hunk --theme github.com/someone/hunk-themes/dracula@v1.2.0   # pin it
hunk --theme-update                                          # re-fetch

It resolves to themes/<name>.toml (or <name>.toml) in that repo, and is cached under ~/.config/hunk/themes/github.com/…. A cache hit never touches the network, so a theme is downloaded once and hunk keeps working offline.

To publish your own, put .toml files in a themes/ directory in any public GitHub repo. That is the whole protocol.

Contributing

Bug reports, themes, and patches all welcome — see CONTRIBUTING.md.

License

MIT © Will Marquardt. See LICENSE.

Documentation

Overview

Command hunk is a themeable diff viewer for the terminal.

Directories

Path Synopsis
internal
diff
Package diff turns unified diff text into a structure the UI can render, and turns a selection of hunks back into a patch git can apply.
Package diff turns unified diff text into a structure the UI can render, and turns a selection of hunks back into a patch git can apply.
git
Package git is the thin layer between hunk and the git binary.
Package git is the thin layer between hunk and the git binary.
theme
Package theme loads hunk's color themes: two built-ins, plus TOML files a user writes locally or pulls from a GitHub repo.
Package theme loads hunk's color themes: two built-ins, plus TOML files a user writes locally or pulls from a GitHub repo.
ui
Package ui renders parsed diffs into a terminal view.
Package ui renders parsed diffs into a terminal view.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL