gah

gah - Git Add Hunks (for AI Agents)

Stage specific hunks non-interactively. Use instead of git add -p which requires interactive input.

Critical Guidelines

1. MUST use anchors, not indices — Indices shift after each staging operation. Anchors stay stable.
2. MUST preview before staging — Never guess hunk numbers. Always run gah preview first.
3. MUST use --dry-run for destructive or uncertain operations — Verify before committing.

When to Use

• Staging partial changes from a file
• Separating unrelated changes into different commits
• Excluding debug/log/console statements from a commit
• Staging only changes relevant to a specific task
• Splitting one large hunk into smaller pieces (--split)
• Staging individual changed lines out of a block (--lines)

Workflow

1. gah preview <file>           → See hunks with anchors
2. Identify target hunks        → Note anchors (not indices)
3. gah add <file> -a <anchor>   → Stage by anchor
4. git commit                   → Commit staged changes
5. Repeat for remaining         → Anchors of unstaged hunks unchanged

Commands

Preview changes

gah preview <file>        # See all hunks with indices and anchors
gah preview --all         # All modified files

Stage hunks

# By anchor (PREFERRED — stable across staging operations)
gah add <file> --anchor Apparent
gah add <file> -a App              # prefix match works

# By index (fragile — indices shift after staging)
gah add <file> --hunks 1,3,5
gah add <file> --hunks 1-3

# By content pattern
gah add <file> --grep "pattern"
gah add <file> --grep "debug|console" --invert  # exclude matches

# By line range — stages ONLY the changed lines in the range, trimming
# the hunk to those lines (NOT the whole overlapping hunk)
gah add <file> --lines 100-150
gah add <file> --lines 142             # one line out of a multi-line edit

# Combine filters
gah add <file> --grep "feature" --lines 50-200

# Verify first
gah add <file> -a Foo --dry-run

Split hunks into smaller pieces

Git lumps nearby changes into one hunk. --split re-diffs at zero context so each change is its own hunk — preview them, then stage independently.

gah preview <file> --split           # finest-grained hunks + anchors
gah add <file> --split -a <anchor>   # stage one split-out change

Splitting strategy:

• Use --split to separate changes git merged into one hunk (gap ≥ 1 line).
• Use --lines to stage individual lines when changes are adjacent — git (and --split) cannot break an adjacent replacement block apart, but --lines trims it to the exact lines you name.
• Always gah preview --split first to see the resolved hunks and anchors.

Error Handling

Error	Cause	Fix
"not a git repository"	Not in git repo	cd to repo root
"No changes to stage"	File has no unstaged changes	Check git status
"hunk N does not exist"	Index out of range	Re-run gah preview
"No hunks match pattern"	Grep found nothing	Try different pattern
"Ambiguous anchor prefix"	Multiple anchors match	Use longer prefix

Example: Splitting Mixed Changes

Scenario: src/auth.rs has both a bugfix and debug logging.

$ gah preview src/auth.rs
[1:ValidateToken] @@ -45,7 +45,9 @@ fn validate_token(
    context line
 +  added line
 -  removed line

[2:DebugPrint] @@ -80,5 +82,10 @@ fn authenticate(
    context line
 +  println!("debug: token = {:?}", token);

src/auth.rs: 2 hunks

# Stage only the bugfix
$ gah add src/auth.rs -a ValidateToken
Staged 1 hunk (3 additions, 1 deletion)

$ git commit -m "fix: validate token expiry correctly"

# Debug logging still unstaged for separate commit or removal