git-hunk

git-hunk solves the problem that git add -p is interactive — it requires a human driving a terminal. LLM agents, shell scripts, and CI pipelines can’t use it. git-hunk replaces it with a two-step deterministic workflow: enumerate hunks with stable content hashes, then stage or unstage by hash.

Installed on PATH, it’s invoked as git hunk <subcommand>. No dependencies beyond git.

Typical workflow

The core pattern is list, select, stage, repeat:

# See what changed
git hunk list

# Output:
# a3f7c21  src/main.zig                  12-18     Add error handling
# b82e0f4  src/main.zig                  45-52     Replace old parser
# e91d3a6  lib/utils.zig                 3-7       new file

# Stage specific hunks by hash
git hunk add a3f7c21

# Remaining hashes are unchanged -- stage another
git hunk add b82e0f4

# Verify what's staged
git hunk list --staged

# Commit the staged hunks
git commit -m "feat: add error handling and update parser"

Listing hunks

Show unstaged hunks (index vs worktree):

git hunk list

Show staged hunks (HEAD vs index):

git hunk list --staged

Filter to a specific file:

git hunk list --file src/main.zig

Machine-readable output for scripting:

git hunk list --porcelain

Output is tab-separated: sha\tfile\tstart_line\tend_line\tsummary

a3f7c21	src/main.zig	12	18	Add error handling
b82e0f4	src/main.zig	45	52	Replace old parser

Flags combine freely:

git hunk list --staged --file src/main.zig --porcelain

Staging hunks

Stage one or more hunks by content hash:

git hunk add a3f7c21                         # one hunk
git hunk add a3f7c21 b82e0f4                 # multiple hunks
git hunk add a3f7 b82e                       # prefix match (min 4 hex chars)
git hunk add a3f7c21 --file src/main.zig     # restrict match to file

On success, prints confirmation to stdout:

staged a3f7c21  src/main.zig

Unstaging hunks

Unstage hunks from the index back to the working tree:

git hunk remove a3f7c21                      # one hunk
git hunk remove a3f7 b82e                    # multiple hunks

Use hashes from git hunk list --staged. Note that staged and unstaged hashes for the same hunk differ (they use different stable line references), so always re-list after switching between staging and unstaging.

Hash stability

Hashes are deterministic and stable: staging or unstaging other hunks in the same file does not change the remaining hashes. This enables sequential workflows where you list once, then stage multiple hunks one at a time.

The hash is computed from:

• File path
• Stable line number (worktree side for unstaged, HEAD side for staged)
• Actual diff content (+ and - lines only)

The “stable line” is the line number from the side that doesn’t shift when hunks are applied to the index. For unstaged hunks, the worktree is immutable, so the + side line number is stable. For staged hunks, HEAD is immutable, so the - side is stable.

Scripting patterns

Stage all hunks in a file:

git hunk list --porcelain --file src/main.zig | cut -f1 | xargs git hunk add

List hunk hashes only:

git hunk list --porcelain | cut -f1

Count hunks per file:

git hunk list --porcelain | cut -f2 | sort | uniq -c

Stage hunks matching a pattern in the summary:

git hunk list --porcelain | grep 'error' | cut -f1 | xargs git hunk add

Prefix matching

SHA prefixes must be at least 4 hex characters. If a prefix matches multiple hunks, the command fails with an ambiguity error. Use a longer prefix or --file to disambiguate.

Error handling

• Nonexistent hash: error: no hunk matching '<sha>' (exit 1)
• Too-short prefix (< 4 chars): error: sha prefix too short (exit 1)
• Ambiguous prefix: error: ambiguous prefix '<sha>' -- matches multiple hunks (exit 1)
• Patch doesn’t apply (stale hashes): error: patch did not apply cleanly -- re-run 'list' and try again (exit 1)
• No unstaged changes: no unstaged changes (exit 1)
• No staged changes: no staged changes (exit 1)

All errors go to stderr. Data goes to stdout. Exit 0 on success, 1 on error.

New and deleted files

New files must be tracked before hunks appear. Use git add -N to register intent to add:

git add -N newfile.txt
git hunk list                  # now shows newfile.txt hunks
git hunk add <sha>             # stages the content

Deleted files appear automatically when a tracked file is removed from the working tree:

rm oldfile.txt
git hunk list                  # shows deletion hunk
git hunk add <sha>             # stages the deletion

References

• Command reference — all commands and flags
• Output format — human and porcelain output details