git-hunk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Hunk

Use

git-hunk

to inspect, stage, unstage, and commit precise text changes without interactive prompts.

Prefer

change_key

over raw line ranges when you need selectors that survive unrelated rescans. Keep

snapshot_id

for safety, treat

change_id

as snapshot-local, and treat raw line ranges as a last resort.

使用

git-hunk

无需交互式提示即可检查、暂存、取消暂存和提交精确的文本变更。

当你需要能在无关重扫描中保留的选择器时，优先使用

change_key

而非原始行范围。务必保留

snapshot_id

以确保安全，将

change_id

视为快照本地标识，仅在万不得已时使用原始行范围。

Quick Start

快速开始

Scan the repo and capture a snapshot:

bash

git-hunk scan --mode stage --json

Inspect a selectable unit:

bash

git-hunk show --mode stage <hunk-id>
git-hunk show --mode stage <change-id> --json
git-hunk show --mode stage <change-key> --json

Apply a selection:

bash

git-hunk stage --snapshot <snapshot-id> --hunk <hunk-id>
git-hunk stage --snapshot <snapshot-id> --change <change-id>
git-hunk stage --snapshot <snapshot-id> --change-key <change-key>
git-hunk stage --snapshot <snapshot-id> --hunk <hunk-id>:new:41-44
git-hunk stage --snapshot <snapshot-id> --change-key <change-key> --dry-run --json

Commit the exact selection directly:

bash

git-hunk commit -m "feat: message" --snapshot <snapshot-id> --change <change-id>
git-hunk commit -m "feat: message" --snapshot <snapshot-id> --change-key <change-key>
git-hunk commit -m "fix: message" --snapshot <snapshot-id> --hunk <hunk-id>:old:18-22
git-hunk commit -m "feat: message" --snapshot <snapshot-id> --change-key <change-key> --dry-run --json

Resolve a file+line hint into durable selectors:

bash

git-hunk resolve --mode stage --snapshot <snapshot-id> --path src/lib.rs --start 42 --json

Recover stale selections without mutating anything:

bash

git-hunk validate --mode stage --snapshot <snapshot-id> --change-key <change-key> --compact --json

扫描仓库并捕获快照：

bash

git-hunk scan --mode stage --json

检查可选单元：

bash

git-hunk show --mode stage <hunk-id>
git-hunk show --mode stage <change-id> --json
git-hunk show --mode stage <change-key> --json

应用选择项：

bash

git-hunk stage --snapshot <snapshot-id> --hunk <hunk-id>
git-hunk stage --snapshot <snapshot-id> --change <change-id>
git-hunk stage --snapshot <snapshot-id> --change-key <change-key>
git-hunk stage --snapshot <snapshot-id> --hunk <hunk-id>:new:41-44
git-hunk stage --snapshot <snapshot-id> --change-key <change-key> --dry-run --json

直接提交精确选择的内容：

bash

git-hunk commit -m "feat: message" --snapshot <snapshot-id> --change <change-id>
git-hunk commit -m "feat: message" --snapshot <snapshot-id> --change-key <change-key>
git-hunk commit -m "fix: message" --snapshot <snapshot-id> --hunk <hunk-id>:old:18-22
git-hunk commit -m "feat: message" --snapshot <snapshot-id> --change-key <change-key> --dry-run --json

将文件+行提示解析为持久化选择器：

bash

git-hunk resolve --mode stage --snapshot <snapshot-id> --path src/lib.rs --start 42 --json

恢复过时的选择项且不修改任何内容：

bash

git-hunk validate --mode stage --snapshot <snapshot-id> --change-key <change-key> --compact --json

Workflow

工作流

Stage mode

暂存模式

Use
```
scan --mode stage
```
for worktree changes relative to the index.
Select by whole hunk,
```
change_id
```
,
```
change_key
```
, or line range.
Prefer
```
--json
```
for agents; ids and
```
snapshot_id
```
come from scan output.
Use
```
scan --compact --json
```
when you want short previews and metadata without the full line arrays.
Use selector bundles from JSON output instead of reconstructing selectors by hand.

使用
```
scan --mode stage
```
查看工作区相对于索引的变更。
可按完整代码块、
```
change_id
```
、
```
change_key
```
或行范围进行选择。
对于Agent，优先使用
```
--json
```
格式；ID和
```
snapshot_id
```
来自扫描输出。
当你需要简短预览和元数据而非完整行数组时，使用
```
scan --compact --json
```
。
优先使用JSON输出中的选择器包，而非手动重构选择器。

Unstage mode

取消暂存模式

Use
```
scan --mode unstage
```
for staged changes relative to
```
HEAD
```
.
Use the same selectors with
```
unstage
```
to remove only part of the index.

bash

git-hunk unstage --snapshot <snapshot-id> --change <change-id>
git-hunk unstage --snapshot <snapshot-id> --change-key <change-key>
git-hunk unstage --snapshot <snapshot-id> --hunk <hunk-id>:old:10-12

使用
```
scan --mode unstage
```
查看已暂存内容相对于
```
HEAD
```
的变更。
使用相同的选择器搭配
```
unstage
```
命令，仅移除索引中的部分内容。

bash

git-hunk unstage --snapshot <snapshot-id> --change <change-id>
git-hunk unstage --snapshot <snapshot-id> --change-key <change-key>
git-hunk unstage --snapshot <snapshot-id> --hunk <hunk-id>:old:10-12

Change keys

变更键（Change keys）

```
change_id
```
is snapshot-bound and should be treated as ephemeral.
```
change_key_scheme
```
is currently
```
v1
```
.
```
change_key
```
is derived from the change content plus nearby context so it survives unrelated rescans, duplicate disambiguation, and hunk splitting caused by unrelated edits.
```
change_key
```
is not guaranteed to survive nearby context edits, renames, or future scheme changes.
Prefer
```
--change-key
```
for multi-step agent workflows where a fresh
```
scan
```
may happen before mutation.

Use

show

stage

unstage

, and

commit

with a

change_key

exactly like a

change_id

```
change_id
```
与快照绑定，应视为临时标识。
当前
```
change_key_scheme
```
版本为
```
v1
```
。
```
change_key
```
由变更内容及附近上下文派生而来，因此在无关重扫描、重复项消歧及无关编辑导致的代码块拆分场景中仍能保留。
若附近上下文被编辑、文件重命名或未来方案变更，
```
change_key
```
可能无法保留。
在多步骤Agent工作流中，优先使用
```
--change-key
```
，尤其是在突变前可能会进行新扫描的场景。
使用
```
show
```
、
```
stage
```
、
```
unstage
```
和
```
commit
```
命令时，
```
change_key
```
的用法与
```
change_id
```
完全一致。

Resolve helper

解析助手

Use
```
resolve
```
when you know a file and approximate line range but do not want to reason about diff internals.
```
resolve
```
returns recommended
```
change_id
```
s,
```
change_key
```
s, hunk selectors, selector bundles, and candidate metadata.
```
--side auto
```
is the default; it prefers
```
new
```
lines in
```
stage
```
mode and
```
old
```
lines in
```
unstage
```
mode.

bash

git-hunk resolve --mode stage --snapshot <snapshot-id> --path src/lib.rs --start 42 --end 47 --json
git-hunk resolve --mode unstage --snapshot <snapshot-id> --path src/lib.rs --start 42 --side old --json

当你知道文件和大致行范围，但不想处理差异内部逻辑时，使用
```
resolve
```
命令。
```
resolve
```
会返回推荐的
```
change_id
```
、
```
change_key
```
、代码块选择器、选择器包及候选元数据。
默认使用
```
--side auto
```
；在暂存模式下优先选择
```
new
```
行，在取消暂存模式下优先选择
```
old
```
行。

bash

git-hunk resolve --mode stage --snapshot <snapshot-id> --path src/lib.rs --start 42 --end 47 --json
git-hunk resolve --mode unstage --snapshot <snapshot-id> --path src/lib.rs --start 42 --side old --json

Validation and dry-run previews

验证与预演（dry-run）

Use
```
validate
```
to compare an old
```
snapshot_id
```
against the current repo state and recover
```
change_key
```
selections before retrying a mutation.
Use
```
stage --dry-run
```
to preview what the index would look like after staging a selection.
Use
```
unstage --dry-run
```
to preview what would remain staged after removing a selection.
Use
```
commit --dry-run
```
to preview the exact files, diffstat, and patch that would be committed.
All dry-run commands use the real selection path against a temporary index, so they reflect actual behavior without mutating the repo.

使用
```
validate
```
命令将旧的
```
snapshot_id
```
与当前仓库状态对比，在重试突变前恢复
```
change_key
```
选择项。
使用
```
stage --dry-run
```
预览暂存选择项后索引的状态。
使用
```
unstage --dry-run
```
预览移除选择项后剩余的已暂存内容。
使用
```
commit --dry-run
```
预览将被提交的精确文件、差异统计及补丁内容。
所有预演命令都会在临时索引上执行真实的选择路径，因此能反映实际行为且不会修改仓库。

Line-range selectors

行范围选择器

Syntax:
```
<hunk-id>:<old|new>:<start-end>
```
.
Use
```
new
```
when selecting added or replacement lines from stage mode.
Use
```
old
```
when selecting the preimage side, especially in unstage mode.
Use
```
show
```
without
```
--json
```
when you want numbered lines in terminal output.
Agents should almost always prefer
```
change_key
```
, then
```
change_id
```
, then
```
resolve
```
, and only use raw line ranges when reproducing a user-specified range exactly.

语法：
```
<hunk-id>:<old|new>:<start-end>
```
。
在暂存模式下选择新增或替换行时，使用
```
new
```
。
在选择原始内容时使用
```
old
```
，尤其是在取消暂存模式下。
若要在终端输出中显示带编号的行，使用不带
```
--json
```
的
```
show
```
命令。
Agent应始终优先使用
```
change_key
```
，其次是
```
change_id
```
，然后是
```
resolve
```
，仅在完全复现用户指定的范围时才使用原始行范围。

Snapshot Discipline

快照规范

Treat
```
snapshot_id
```
as mandatory for any mutating command.
Rescan after every successful
```
stage
```
,
```
unstage
```
, or
```
commit
```
.
If the command returns
```
stale_snapshot
```
, do not retry blindly; inspect
```
error.details
```
or run
```
validate
```
to recover with the fresh snapshot.
```
change_key
```
can survive rescans, but the mutation still needs a fresh
```
snapshot_id
```
before it applies.

任何突变命令都必须指定
```
snapshot_id
```
。
每次成功执行
```
stage
```
、
```
unstage
```
或
```
commit
```
后重新扫描。
若命令返回
```
stale_snapshot
```
，不要盲目重试；查看
```
error.details
```
或运行
```
validate
```
命令，结合新快照恢复操作。
```
change_key
```
可在重扫描后保留，但突变仍需新的
```
snapshot_id
```
才能执行。

Plan Files

计划文件

Use a plan file when passing many selectors or when another tool is driving the workflow.

json

{
  "snapshot_id": "s_123",
  "selectors": [
    { "type": "hunk", "id": "h_abc" },
    { "type": "change", "id": "c_def" },
    { "type": "change_key", "key": "ck_xyz" },
    {
      "type": "line_range",
      "hunk_id": "h_xyz",
      "side": "new",
      "start": 41,
      "end": 44
    }
  ]
}

Run it with:

bash

git-hunk stage --plan plan.json --json
git-hunk stage --plan - --json < plan.json
git-hunk commit -m "refactor: split change" --plan plan.json --json

当需要传递多个选择器，或由其他工具驱动工作流时，使用计划文件。

json

{
  "snapshot_id": "s_123",
  "selectors": [
    { "type": "hunk", "id": "h_abc" },
    { "type": "change", "id": "c_def" },
    { "type": "change_key", "key": "ck_xyz" },
    {
      "type": "line_range",
      "hunk_id": "h_xyz",
      "side": "new",
      "start": 41,
      "end": 44
    }
  ]
}

执行方式：

bash

git-hunk stage --plan plan.json --json
git-hunk stage --plan - --json < plan.json
git-hunk commit -m "refactor: split change" --plan plan.json --json

Failure Handling

故障处理

If you get
```
ambiguous_line_range
```
, widen the range to cover the full atomic change or fall back to the
```
change_id
```
shown by
```
scan
```
.
Use
```
error.category
```
,
```
error.retryable
```
, and
```
error.details
```
from JSON errors to decide whether to rescan, retry, or fall back.
If a path appears under
```
unsupported
```
, do not try to force it through
```
git-hunk
```
; use normal git commands or a different workflow for conflicts, renames, copies, binary files, or non-UTF-8 diffs.
If there is nothing staged,
```
commit
```
fails unless
```
--allow-empty
```
is set.

若出现
```
ambiguous_line_range
```
错误，扩大范围以覆盖完整的原子变更，或改用
```
scan
```
命令显示的
```
change_id
```
。
利用JSON错误中的
```
error.category
```
、
```
error.retryable
```
和
```
error.details
```
决定是否重新扫描、重试或改用其他方案。
若路径出现在
```
unsupported
```
下，不要强行使用
```
git-hunk
```
处理；对于冲突、重命名、复制、二进制文件或非UTF-8差异，使用常规Git命令或其他工作流。
若没有已暂存内容，
```
commit
```
命令会失败，除非设置
```
--allow-empty
```
参数。

Practical Defaults

实用默认规则

Prefer
```
change_key
```
over line ranges whenever both are available.
Prefer
```
resolve
```
when you only have a file+line hint.
Prefer
```
validate
```
when an old snapshot goes stale but you still have
```
change_key
```
s.
Prefer
```
stage --dry-run
```
,
```
unstage --dry-run
```
, or
```
commit --dry-run
```
before a risky atomic mutation from a dirty tree.
Prefer
```
commit
```
with selectors when the user asked for a commit and you already know the exact changes.
Prefer
```
stage
```
first when you need to inspect the staged result before committing.
Keep commits atomic by scanning, selecting a minimal set, committing, then rescanning for the next commit.

只要可用，优先使用
```
change_key
```
而非行范围。
仅知道文件+行提示时，优先使用
```
resolve
```
。
当旧快照过时但仍有
```
change_key
```
时，优先使用
```
validate
```
。
在脏工作区执行高风险原子突变前，优先使用
```
stage --dry-run
```
、
```
unstage --dry-run
```
或
```
commit --dry-run
```
。
当用户要求提交且你已明确知道精确变更时，优先使用带选择器的
```
commit
```
命令。
若需要在提交前检查暂存结果，优先先执行
```
stage
```
命令。
通过扫描、选择最小变更集、提交、再扫描的方式保持提交的原子性。