From cbaa844250db337944195ac75c9af40c6a9da6b9 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 29 Jul 2026 00:56:49 +0000 Subject: [PATCH] docs: align README with the CLI surface The README advertised difftool support without setup instructions and omitted `hunk stash show`, `--staged`, and the hosted docs site. Add the missing surface, restructure the grab-bag Advanced section into clear Integrations and Configuration sections, and fold the loose config footnotes into the example so each section reads top to bottom. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01KHY9ReVesQXwKdRU47MwJ9 --- .changeset/readme-surface-cleanup.md | 2 + README.md | 165 +++++++++++++-------------- 2 files changed, 79 insertions(+), 88 deletions(-) create mode 100644 .changeset/readme-surface-cleanup.md diff --git a/.changeset/readme-surface-cleanup.md b/.changeset/readme-surface-cleanup.md new file mode 100644 index 000000000..a845151cc --- /dev/null +++ b/.changeset/readme-surface-cleanup.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/README.md b/README.md index 65e4026b7..09059c9b7 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,8 @@ Hunk is a review-first terminal diff viewer for agent-authored changesets, built +Full documentation, including guides and generated CLI/config references, lives at **[hunk.dev/docs](https://hunk.dev/docs/)**. + ## Install ```bash @@ -44,7 +46,7 @@ brew install hunk Requirements: -- Node.js 18+ +- Node.js 18+ (npm installs; Homebrew and Nix binaries are self-contained) - macOS, Linux, or Windows - Git recommended for most workflows @@ -57,44 +59,46 @@ hunk # show help hunk --version # print the installed version ``` -### Working with Git +### Review Git changes Hunk mirrors Git's diff-style commands, but opens the changeset in a review UI instead of plain text. ```bash -hunk diff # review current repo changes, including untracked files -hunk diff --watch # auto-reload as the working tree changes -hunk show # review the latest commit -hunk show HEAD~1 # review an earlier commit +hunk diff # working tree changes, untracked files included +hunk diff --staged # staged changes only +hunk diff main...feature # compare against a target +hunk show # the latest commit +hunk show HEAD~1 # an earlier commit +hunk stash show # a stash entry ``` -### Working with Jujutsu and Sapling +Add `--watch` to auto-reload as the input changes, and `--exclude-untracked` when you want tracked changes only. Arguments after `--` are pathspecs, as in `hunk show HEAD~1 -- src/ui`. + +### Review in Jujutsu and Sapling -Hunk auto-detects Jujutsu and Sapling checkouts, so `hunk diff [revset]` and `hunk show [revset]` use native revsets inside jj or Sapling workspaces. To override VCS detection, set `vcs = "git"` or `vcs = "jj"` or `vcs = "sl"` in [config](#config). +Hunk auto-detects Jujutsu and Sapling checkouts, so `hunk diff [revset]` and `hunk show [revset]` use native revsets inside jj or Sapling workspaces. To override VCS detection, set `vcs = "git"` or `vcs = "jj"` or `vcs = "sl"` in [config](#configuration). -### Working with raw files and patches +### Review files and patches ```bash -hunk diff before.ts after.ts # compare two files directly -hunk diff before.ts after.ts --watch # auto-reload when either file changes -git diff --no-color | hunk patch - # review a patch from stdin +hunk diff before.ts after.ts # compare two files directly +hunk patch change.patch # review a patch file +git diff --no-color | hunk patch - # review a patch from stdin ``` -Watch mode remains continuous. Direct-file and Git-backed reviews normally use filesystem observation to refresh promptly, with periodic polling retained as a fallback for missed events or unavailable watchers. Jujutsu and Sapling reviews currently use polling rather than filesystem observation. +`--watch` works with any input Hunk can reopen — direct files, repositories, and patch files, but not stdin snapshots. -### Working with agents +### Review with an agent -1. Open Hunk in another terminal with `hunk diff` or `hunk show`. +1. Open Hunk in one terminal with `hunk diff` or `hunk show`. 2. Tell your agent to add the skill file returned by `hunk skill path`. -3. Ask your agent to use the skill against the live Hunk session. - -A good generic prompt is: +3. Ask your agent to use the skill against the live Hunk session: ```text Load the Hunk skill and use it for this review. Run `hunk skill path` to get the skill path. ``` -For the full live-session and `--agent-context` workflow guide, see [docs/agent-workflows.md](docs/agent-workflows.md). Experimental rich STML note bodies require starting the review with `--experimental`; plain agent notes remain the default. +You keep the TUI; the agent inspects and steers the same live review through `hunk session` commands and leaves inline notes beside the code. See [docs/agent-workflows.md](docs/agent-workflows.md) for the full workflow, including prewritten `--agent-context` note sidecars and experimental STML markup. ## Feature comparison @@ -112,67 +116,16 @@ For the full live-session and `--agent-context` workflow guide, see [docs/agent- Hunk is optimized for reviewing a full changeset interactively. -## Advanced - -### Config - -You can persist preferences to a config file: - -- `~/.config/hunk/config.toml` -- `.hunk/config.toml` - -Example: - -```toml -theme = "github-dark-default" # any built-in theme id, auto, or custom -mode = "auto" # auto, split, stack -vcs = "git" # git, jj, sl -watch = false -exclude_untracked = false -line_numbers = true -tab_width = 4 # tab stops, 1-16 -wrap_lines = false -menu_bar = true -agent_notes = false -prompt_save_view_preferences = true -transparent_background = false -``` - -Choose a built-in theme, `auto`, or a custom theme with `theme`. See -[docs/themes.md](docs/themes.md) for automatic selection, custom theme tables, -syntax scopes, and legacy syntax-table migration. +## Integrations -`exclude_untracked` affects Git/Sapling working-tree `hunk diff` sessions only. -`tab_width` controls source-code tab stops and can be overridden with `-x4` or `--tab-width 4`. -`prompt_save_view_preferences = false` disables the quit prompt for saving changed view preferences. -`transparent_background` can also be written as `transparentBackground`. - -### Keybindings - -Every keyboard shortcut is a named command, and a `[keybindings]` table in your -user config remaps command ids to the keys you want them on — several keys per -command, exclusive claims over defaults, and `false` to unbind. See -[docs/keybindings.md](docs/keybindings.md) for the rules, the chord grammar, -and the full table of built-in commands and their default keys. - -### Git integration +### Git pager Set Hunk as your Git pager so `git diff` and `git show` open in Hunk automatically: -> [!NOTE] -> Untracked files are auto-included only for Hunk's own `hunk diff` working-tree loader. If you open `git diff` through `hunk pager`, Git still decides the patch contents, so untracked files will not appear there. - ```bash git config --global core.pager "hunk pager" ``` -Or in your Git config: - -```ini -[core] - pager = hunk pager -``` - If you want to keep Git's default pager and add opt-in aliases instead: ```bash @@ -180,7 +133,22 @@ git config --global alias.hdiff "-c core.pager=\"hunk pager\" diff" git config --global alias.hshow "-c core.pager=\"hunk pager\" show" ``` -### Jujutsu pager integration +> [!NOTE] +> In pager mode Git decides the patch contents, so untracked files will not appear there. Only Hunk's own `hunk diff` working-tree loader auto-includes them. + +### Git difftool + +To use Hunk as an explicit `git difftool`: + +```bash +git config --global diff.tool hunk +git config --global difftool.hunk.cmd 'hunk difftool "$LOCAL" "$REMOTE" "$MERGED"' +git config --global difftool.prompt false +``` + +Git invokes the difftool once per file pair; prefer `hunk diff` when you want the full-changeset review stream. + +### Jujutsu pager To use Hunk as jj's pager, run `jj config edit --user` and update: @@ -190,7 +158,7 @@ pager = ["hunk", "pager"] diff-formatter = ":git" ``` -### Sapling pager integration +### Sapling pager To use Hunk as Sapling's pager, run `sl config -u` and update: @@ -199,22 +167,44 @@ To use Hunk as Sapling's pager, run `sl config -u` and update: pager = hunk pager ``` +## Configuration + +You can persist preferences to a config file: + +- `~/.config/hunk/config.toml` +- `.hunk/config.toml` (repository-local, overrides user settings) + +Example: + +```toml +theme = "github-dark-default" # any built-in theme id, auto, or custom +mode = "auto" # auto, split, stack +vcs = "git" # git, jj, sl +watch = false +exclude_untracked = false # Git/Sapling working-tree reviews only +line_numbers = true +tab_width = 4 # tab stops, 1-16; also -x4 / --tab-width 4 +wrap_lines = false +hunk_headers = true +menu_bar = true +agent_notes = false +prompt_save_view_preferences = true # offer to save view changes on quit +transparent_background = false +``` + +See [docs/themes.md](docs/themes.md) for automatic theme selection, custom theme tables, and syntax scopes, and the [config reference](https://hunk.dev/docs/reference/config/) for every key, default, alias, and per-command `[section]` scoping. + +### Keybindings + +Every keyboard shortcut is a named command, and a `[keybindings]` table in your user config remaps command ids to the keys you want them on — several keys per command, exclusive claims over defaults, and `false` to unbind. See [docs/keybindings.md](docs/keybindings.md) for the rules, the chord grammar, and the full table of built-in commands and their default keys. + ### Extensions (experimental) -The extension API is experimental and may change in breaking ways between -minor releases while it stabilizes; breaking changes are called out in -release notes. +The extension API is experimental and may change in breaking ways between minor releases while it stabilizes; breaking changes are called out in release notes. -Hunk loads plain TypeScript extensions from `~/.config/hunk/extensions/`, from a -repository's `.hunk/extensions/` (after you explicitly trust that repository), -and from `--extension ` for development. `--no-extensions` turns those off -for one run; Hunk's own bundled backends (Git, Jujutsu, and Sapling) stay loaded. +Hunk loads plain TypeScript extensions from `~/.config/hunk/extensions/`, from a repository's `.hunk/extensions/` (after you explicitly trust that repository), and from `--extension ` for development. `--no-extensions` turns those off for one run; Hunk's own bundled backends (Git, Jujutsu, and Sapling) stay loaded. -A Phase 1 extension can contribute themes and file-extension → language -mappings, add a VCS backend, rewrite the changeset before review (collapse -lockfiles, reorder files by review priority), replace the file-navigation -sidebar with its own React component, react to lifecycle events, and show -transient messages: +An extension can contribute themes and file-extension → language mappings, add a VCS backend, rewrite the changeset before review (collapse lockfiles, reorder files by review priority), replace the file-navigation sidebar with its own React component, react to lifecycle events, and show transient messages: ```ts // ~/.config/hunk/extensions/collapse-lockfiles.ts @@ -229,8 +219,7 @@ export default function (hunk: HunkExtensionAPI) { } ``` -See [docs/extensions.md](docs/extensions.md) for the full API, the trust model, -and the `[extensions]` / `[extension.]` config reference. +See [docs/extensions.md](docs/extensions.md) for the full API, the trust model, and the `[extensions]` / `[extension.]` config reference. ### OpenTUI component