git-staging（git 暂存）

Non-interactive Git Staging

When to use this skill

Use this skill when you need to:

• Stage only specific hunks from a file (not the entire file)
• Stage only specific lines within a hunk
• Avoid interactive git commands (git add -p, git add -i, etc.)
• Programmatically control exactly what gets staged

Step 1: Assess the changes

Before choosing a staging method, determine what changes exist:

git status                    # See which files have changes
git diff --no-ext-diff        # See all unstaged changes
git diff --cached --no-ext-diff  # See already-staged changes

Decision tree:

• If only ONE file has changes and you want ALL of them staged → use git add <file>
• If ONE file has multiple unrelated hunks and you want only SOME → use Method 2 or 3
• If MULTIPLE files need staging → stage per-file with git add for each, or selectively with patch method

Why not use git add -p?

Interactive git commands require a TTY and human input. AI agents cannot reliably fake interactive sessions - attempts using echo "y" or yes are fragile and often fail. Instead, construct patches programmatically and apply them directly to the index.

Core technique

The key insight is that git apply --cached applies a patch directly to the staging area (index) without modifying the working tree. This lets you stage precise changes non-interactively.

Temporary files

All temporary patch files should be written to tmp/ within the repository (not /tmp) to avoid permission prompts. Ensure the directory exists first:

mkdir -p tmp

Methods

Method 1: Stage entire file

When you want to stage all changes in a file:

git add <file>

Method 2: Stage specific hunks via patch

When you need to stage only certain hunks from a file:

1. Generate the full diff for the file: git diff <file> > tmp/full.patch
2. Edit the patch to keep only the hunks you want to stage (use the Edit tool or create a new file with only the desired hunks)
3. Apply the edited patch to the index: git apply --cached tmp/selected.patch

Method 3: Stage specific lines within a hunk

When you need to stage only certain lines within a hunk, you must carefully edit the patch to maintain validity:

1. Generate the diff: git diff <file> > tmp/full.patch
2. Edit the patch, following these rules for the hunk you're modifying:

- Keep the @@ hunk header but adjust the line counts - To exclude an added line (+): remove the entire line from the patch - To exclude a removed line (-): change - to a space (`) to make it context - Adjust the line counts in the @@ -X,Y +X,Z @@` header to match

1. Apply: git apply --cached tmp/selected.patch

Patch format reference

A unified diff patch has this structure:

diff --git a/file.txt b/file.txt
index abc123..def456 100644
--- a/file.txt
+++ b/file.txt
@@ -10,6 +10,8 @@ optional context label
 context line (unchanged)
-removed line
+added line
 context line (unchanged)

Hunk header format

@@ -START,COUNT +START,COUNT @@

• First pair: original file (lines being removed or used as context)
• Second pair: new file (lines being added or used as context)
• COUNT = number of lines in that side of the hunk (context + changes)

Line prefixes

• `` (space): context line (unchanged, appears in both versions)
• -: line only in original (will be removed)
• +: line only in new version (will be added)

Example: Staging only the second hunk

Given a file with two hunks of changes:

# Generate full diff
git diff --no-ext-diff myfile.py > tmp/full.patch

The patch might look like:

diff --git a/myfile.py b/myfile.py
index abc123..def456 100644
--- a/myfile.py
+++ b/myfile.py
@@ -5,6 +5,7 @@ import os
 def foo():
     pass
+    # Added comment in first hunk

 def bar():
@@ -20,6 +21,7 @@ def bar():
 def baz():
     pass
+    # Added comment in second hunk

To stage only the second hunk, create a new patch with just that hunk:

diff --git a/myfile.py b/myfile.py
index abc123..def456 100644
--- a/myfile.py
+++ b/myfile.py
@@ -20,6 +21,7 @@ def bar():
 def baz():
     pass
+    # Added comment in second hunk

Then apply:

git apply --cached tmp/second-hunk.patch

Example: Excluding specific added lines

If you have a hunk with multiple additions but only want to stage some:

Original hunk:

@@ -10,4 +10,7 @@
 existing line
+line I want to stage
+line I do NOT want to stage
+another line I want to stage
 more context

Edit to exclude the unwanted line (remove it entirely and adjust count):

@@ -10,4 +10,6 @@
 existing line
+line I want to stage
+another line I want to stage
 more context

Note: The +10,7 became +10,6 because we removed one added line.

Verification

After applying, verify what was staged:

git diff --cached          # Show staged changes
git diff                   # Show unstaged changes (should include excluded hunks)
git status                 # Overview of staged/unstaged state

Common pitfalls

1. Invalid line counts: If the @@ header counts don't match the actual lines in the hunk, git apply will fail. Always recount after editing.
2. Missing newline at EOF: Patches are sensitive to trailing newlines. Watch for \ No newline at end of file markers.
3. Whitespace corruption: Ensure context lines start with a space, not an empty prefix. Some editors strip trailing spaces.
4. Index mismatch: The index abc123..def456 line is optional for git apply --cached. If you have issues, try removing it.

Troubleshooting

If git apply --cached fails:

1. Test the patch first without --cached: git apply --check tmp/selected.patch
2. Use verbose mode to see what's happening: git apply --cached -v tmp/selected.patch
3. Common error messages:

- "patch does not apply": Line counts are wrong or context doesn't match - "patch fragment without header": Missing the diff --git or ---/+++ lines