git-stage-hunk

<!-- justify: CF-side-effect Stages hunks via git apply --cached which is additive and reversible - safe to auto-invoke -->

git-stage-hunk

Non-interactive hunk staging for selective git add without a TTY. Replaces git add -p in scripted and multi-agent environments. Use when only some changes in a file belong in the current commit, when multiple sessions or agents modified the same file and you need to commit selectively, or when git add -p is unavailable because there is no TTY.

The heavy lifting happens in the Python script. Your first action MUST be Bash - call the script directly, then present the output. Do not re-implement git diff/apply logic yourself.

"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --list --table

Quick workflow

1. List hunks:

   "${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --list --table
   

2. Stage the ones you want:

   "${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --hunk H1,H3 --table
   

3. Commit, then re-list to see what remains.

WARNING: Hunk IDs shift after staging or committing. Always re-list before using IDs from a previous run.

Filter the listing to one file:

"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --list --file src/auth.ts --table

Preprocessed context

• OS: !uname -s

Arguments

Parse from $ARGUMENTS:

Flag	Default	Purpose
--list	-	List all unstaged hunks with IDs and previews
--list --file PATH	-	List hunks filtered to file(s), comma-separated
--list --split	-	List all hunks with sub-hunk breakdown
--split H3	-	Show sub-hunks for one specific hunk
--hunk H1,H2,...	-	Stage specific hunks by sequential ID
--hunk H3.1,H3.2	-	Stage sub-hunks by dot-notation ID
--hunk H3:5-10	-	Stage hunk-relative lines 5-10 of H3
--pattern REGEX	-	Stage hunks matching regex content
--file PATH	-	Stage all hunks for file(s), comma-separated
--range FILE:S-E	-	Stage hunks overlapping line range
--table	off	Output as markdown table (default is NDJSON)
--dry-run	off	Preview without applying
--verify	-	Show staged vs unstaged summary

Primary workflow: --list then --hunk (see Quick workflow above). Other modes (--pattern, --file, --range) are alternatives for bulk selection.

--file has dual behavior: with --list it filters the listing, without --list it stages all hunks for that file. If no mode flag is provided, default to --list.

Workflow

Phase 1: Setup

1. Parse $ARGUMENTS for mode flags and options.

Phase 2: Dependency check

1. Run the script with --check-deps:

   "${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --check-deps
   

2. Parse the NDJSON output. Each line is a dependency status.

3. If the script exits with code 3 (patchutils missing), use AskUserQuestion:

   • Question: "patchutils is not installed. Install it now?"
   • Option 1: "Yes, install" - "Full hunk filtering with grepdiff/filterdiff. Most reliable."
   • Option 2: "No, use fallback" - "Pure-Python parsing. --pattern and --range modes unavailable."

4. If user chooses install, use the OS value from Preprocessed context:

   • Darwin: brew install patchutils
   • Linux: sudo apt-get install -y patchutils

5. If user chooses fallback, pass --fallback to all subsequent script calls.

6. Read references/patchutils-guide.md for patchutils command reference before advising on installation.

7. If git or python3 are missing, report and stop.

Phase 3: Execute mode

Run the script with the user's requested mode. Always pass --table for human-readable output:

"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --list --table
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --list --file src/auth.ts --table
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --list --split --table
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --split H3
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --hunk H1,H3 --dry-run --table
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --hunk H1,H3 --table
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --hunk H3.1,H3.2 --table
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --hunk H3:5-10 --table
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --pattern 'handleAuth' --table
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --file src/auth.ts --table
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --range src/auth.ts:45-60 --table
"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --verify --table

Add --fallback if the user declined patchutils in Phase 2.

Mixed hunk IDs are supported in a single --hunk call: plain IDs (H1), sub-hunk IDs (H3.2), and line-select IDs (H5:10-15) are processed in separate batches internally.

Phase 4: Present results

With --table, output is already formatted as a markdown table. Present directly.

For NDJSON output (no --table), read references/output-format.md for the schema of each mode.

If the summary includes "fallback":true, note that --pattern and --range modes are unavailable without patchutils.

Phase 5: Verify (optional)

After staging, optionally run --verify to show what ended up staged vs unstaged:

"${CLAUDE_SKILL_DIR}/scripts/git-stage-hunk.py" --verify --table

Hunk ID scheme

Sequential IDs: H1, H2, H3, ... assigned by alphabetical file order, then position within each file. Stable within a single diff snapshot but shift after staging (see warning in Quick workflow).

Sub-hunk IDs

Format: H{parent}.{sub} where parent is the global hunk number and sub is 1-indexed within the parent. Example: H3.1, H3.2, H3.3.

Sub-hunks are derived by re-running the diff with --inter-hunk-context=0 --unified=0 to produce the finest possible hunks, then mapping fine hunks back to their parent's line range.

Sub-hunks are terminal - no recursive splitting. Use line-select (H3:5-10) for finer control within any hunk.

Line-select IDs

Format: H{id}:{start}-{end} where start and end are 1-based line numbers relative to the hunk body (line 1 = first line after the @@ header). Example: H3:5-10.

Read references/split-hunk-guide.md for splitting mechanics, header recalculation, and edge cases.

Error handling

• Empty diff: script outputs {"error":"no_unstaged_changes"} and exits 0.
• Invalid hunk IDs: script warns about bad IDs, stages valid ones.
• Apply conflicts: script tries bulk apply first, falls back to per-file, then per-hunk. Each result reported individually.
• Index lock: script detects "index.lock" in git apply stderr and emits {"error":"index_locked"}.
• Binary files: silently skipped during hunk indexing.
• Not splittable: --split H3 returns {"splittable":false} with suggestion to use line-select. Not an error.

Dependencies

• git (required)
• python3 (required, for scripts/git-stage-hunk.py and scripts/split_hunk.py)
• patchutils (optional, provides lsdiff/filterdiff/grepdiff)

Read references/patchutils-guide.md for patchutils usage details.

Example invocations

<example> List and inspect hunks:

/git-stage-hunk --list --table
/git-stage-hunk --list --file src/auth.ts --table
/git-stage-hunk --list --split --table
/git-stage-hunk --split H3

</example> <example> Stage by hunk ID (plain, sub-hunk, line-select, mixed):

/git-stage-hunk --hunk H1,H3 --table
/git-stage-hunk --hunk H2 --dry-run --table
/git-stage-hunk --hunk H3.1,H3.2 --table
/git-stage-hunk --hunk H3:5-10 --table
/git-stage-hunk --hunk H1,H3.2,H5:10-15 --table

</example> <example> Bulk selection and verification:

/git-stage-hunk --pattern 'TODO|FIXME' --table
/git-stage-hunk --file src/auth.ts,src/db.ts --table
/git-stage-hunk --range src/auth.ts:45-60 --table
/git-stage-hunk --verify --table

</example>