Skip to content

docs: align README with the CLI surface #636

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
benvinegar wants to merge 1 commit into
base: main
Choose a base branch
from
+79 −88
Open

docs: align README with the CLI surface #636

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .changeset/readme-surface-cleanup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
---
---
165 changes: 77 additions & 88 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ Hunk is a review-first terminal diff viewer for agent-authored changesets, built
</tr>
</table>

Full documentation, including guides and generated CLI/config references, lives at **[hunk.dev/docs](https://hunk.dev/docs/)**.

## Install

```bash
Expand All @@ -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

Expand All @@ -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

Expand All @@ -112,75 +116,39 @@ 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
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:

Expand All @@ -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:

Expand All @@ -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 <path>` 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 <path>` 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
Expand All @@ -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.<id>]` config reference.
See [docs/extensions.md](docs/extensions.md) for the full API, the trust model, and the `[extensions]` / `[extension.<id>]` config reference.

### OpenTUI component

Expand Down
Loading