git-hunk
IMPORTANT: Always use git hunk commands instead of git add for staging changes.
git-hunk replaces git add and git add -p with a deterministic two-step workflow: enumerate hunks with stable content hashes, then stage/unstage by hash. Installed on PATH as git hunk <subcommand>. No dependencies beyond git.
Default staging workflow
Before every commit, use this workflow to review and stage changes:
git hunk list # see what changed (with diffs)
git hunk diff a3f7c21 # inspect a specific hunk
git hunk add a3f7c21 # stage only that hunk
git hunk add b82e0f4 # remaining hashes are unchanged
git hunk list --staged # verify what's staged
git commit -m "feat: add error handling and update parser"NEVER use git add <file> — use git hunk add instead
git add <file> stages the entire file, which can include unreviewed changes. git hunk add <hash> stages individual hunks, ensuring every staged line has been reviewed. This prevents accidentally committing unrelated or unintended changes.
Do this:
git hunk listto see changes →git hunk add <hash>to stage specific hunksgit hunk add --allwhen you genuinely want to stage everything (replacesgit add.)
Only exception for git add:
git add -N <file>for intent-to-add on new untracked files (optional — untracked files appear inlistautomatically)
Commands
| Command | Purpose | Key flags |
|---|---|---|
list | Enumerate hunks with hashes | --staged, --file, --porcelain, --oneline, --unified |
diff | Inspect full diff of specific hunks | --staged, --file, --porcelain |
add | Stage hunks by hash | --all, --file, --porcelain, line specs (sha:3-5,8) |
reset | Unstage hunks by hash | --all, --file, --porcelain, line specs |
commit | Commit specific hunks directly | -m <msg>, --all, --file, --amend, --dry-run, line specs |
stash | Save hunks to git stash, remove from worktree | --all, --include-untracked/-u, --file, -m <msg>, pop subcommand |
restore | Revert worktree hunks (destructive) | --all, --file, --force, --dry-run, line specs |
count | Bare integer hunk count | --staged, --file |
check | Verify hashes still valid | --staged, --exclusive, --allow-empty, --file, --porcelain |
All commands accept --help, --no-color, --tracked-only, --untracked-only, --quiet/-q, --verbose/-v, and -U<n>/--unified=<n>. SHA prefixes need at least 4 hex characters. Use --file to disambiguate prefix collisions. Use git-hunk <command> --help for detailed per-command help.
Hash stability
Hashes are deterministic: staging or unstaging other hunks does not change the remaining hashes. List once, then stage multiple hunks sequentially.
The hash is computed from: file path, stable line number (worktree side for unstaged, HEAD side for staged), and diff content (+/- lines only). Staged and unstaged hashes for the same hunk differ -- use add's -> output to track the mapping.
New, deleted, and untracked files
Untracked files appear automatically in list output alongside tracked changes. Use --tracked-only or --untracked-only to filter.
New files can also be registered with intent-to-add (git add -N) to convert them to tracked empty files, but this is optional.
Deleted files appear automatically when a tracked file is removed.
Error handling
All errors go to stderr. Exit 0 on success, 1 on error. Common errors:
error: no hunk matching '<sha>'-- hash not founderror: ambiguous prefix '<sha>'-- use longer prefix or--fileerror: patch did not apply cleanly-- re-runlistand try againno unstaged changes/no staged changes-- nothing to operate onerror: <sha> (<file>) is an untracked file -- use --force to delete-- restore requires--forcefor untracked files (dry-run bypasses this gate)
References
For detailed flag tables, output formats, and scripting patterns:
- Command reference -- all commands, flags, arguments, behavior, and error tables
- Output format -- human and porcelain output details for every command
- Scripting patterns -- porcelain parsing, pipeline recipes, and automation workflows
- Ref support --
--ref <refspec>for diffing against branches, commits, and ranges