Interactive staging (git add -p)

Basic Concepts of Interactive Staging (git add -p)

Interactive staging is a powerful feature provided by Git that allows developers to selectively stage specific parts of a file rather than the entire file. This feature is triggered by the git add -p command, where -p is short for --patch. When executing this command, Git displays each changed "hunk" in the file one by one and asks whether to stage that portion of the change.

Why Interactive Staging is Needed

During development, it's common to encounter situations where a file contains multiple logically independent changes. For example:

// Modified user login logic
function handleLogin() {
  // Added login validation
  if (!validateUser()) {
    return false;
  }
  
  // Original logic
  // ...
}

// Fixed a bug in user profile display
function displayProfile() {
  // Bug fix
  if (user.avatar === null) {
    showDefaultAvatar();
  }
  // ...
}

This file contains two different modifications: one adds login validation, and the other fixes a profile display bug. Using git add . would stage both changes together, but git add -p allows you to choose to stage only one of the changes.

Basic Usage of Interactive Staging

After executing git add -p, Git displays an interface similar to the following:

diff --git a/src/utils.js b/src/utils.js
index 1a2b3c4..5d6e7f8 100644
--- a/src/utils.js
+++ b/src/utils.js
@@ -10,6 +10,9 @@ function handleLogin() {
   if (!validateUser()) {
     return false;
   }
+  if (isAccountLocked()) {
+    throw new Error('Account locked');
+  }
   
   // Original logic
   // ...
Stage this hunk [y,n,q,a,d,s,e,?]? 

Here, Git displays a hunk of changes and waits for the user to input a command to decide how to handle this change.

Common Commands in Interactive Staging

In the interactive staging interface, the following commands can be used:

• y (yes): Stage the current hunk
• n (no): Do not stage the current hunk
• q (quit): Exit interactive staging without staging the remaining hunks
• a (all): Stage the current hunk and all remaining hunks in the file
• d (done): Do not stage the current hunk or any remaining hunks in the file
• s (split): Attempt to split the current hunk into smaller hunks
• e (edit): Manually edit the current hunk
• ?: Show help information

Splitting Large Hunks (split)

Sometimes a hunk contains multiple logical changes. The s command can be used to split it:

Stage this hunk [y,n,q,a,d,s,e,?]? s
Split into 2 hunks.

After splitting, each smaller hunk can be handled separately.

Manually Editing Hunks (edit)

When automatic splitting doesn't meet your needs, you can use the e command to manually edit the hunk:

Stage this hunk [y,n,q,a,d,s,e,?]? e

This opens an editor where you can precisely control which lines should be staged. When editing:

• Delete lines that should not be staged
• Keep lines that should be staged
• Lines starting with # are comments and will be ignored

Practical Application Example

Suppose we have a React component file with multiple modifications:

// Header.js
function Header() {
  // Added multilingual support
  const { t } = useTranslation();
  
  // Modified navigation style
  return (
    <header className="new-header-style">
      <nav>
        <a href="/">{t('home')}</a>
        <a href="/about">{t('about')}</a>
      </nav>
      
      // Added user avatar display
      {user && <Avatar user={user} />}
    </header>
  );
}

Using git add -p Header.js, you can separately handle:

1. Changes related to multilingual support
2. Navigation style modifications
3. Addition of user avatar display

Advanced Technique: Regular Expression Matching

You can configure git config to define which changes should be automatically staged:

git config --global add.interactive.useBuiltin false
git config --global add.interactive.patterns '/(TODO|FIXME)/'

This will highlight changes containing TODO or FIXME.

Combining with git stash

Interactive staging can be combined with git stash to create partial stashes:

git add -p  # Select changes to stage
git stash save --keep-index  # Stash unstaged changes

Handling Merge Conflicts

Interactive staging is particularly useful when resolving merge conflicts:

git mergetool  # Resolve conflicts
git add -p     # Selectively stage resolved conflicts

Application in CI/CD Pipelines

You can use interactive staging in pre-commit hooks for checks:

#!/bin/sh
if ! git add -n -p; then
  echo "Error in staging changes"
  exit 1
fi

Common Issue Resolution

Issue 1: Accidentally staged unwanted changes
Solution: Use git reset -p for interactive unstaging

Issue 2: Hunk is too large to split
Solution: Use the e command to manually edit, or commit partial changes first and then handle the remaining parts

Issue 3: Want to view current staging status
Solution: During interactive staging, open a new terminal and execute git diff --cached

Integration with Other Git Commands

Interactive staging can be combined with other Git commands:

# Interactive staging followed by immediate commit
git add -p && git commit

# Interactive staging followed by status check
git add -p && git status

# Interactive staging followed by creating a new branch
git add -p && git checkout -b new-feature

Practices in Large Projects

In large projects, interactive staging can help:

1. Separate feature development and bug fixes
2. Prepare clean patches
3. Create logically clear commit history
4. Prevent unnecessary changes from entering version control

Performance Considerations

For very large change sets, interactive staging may become slow. In such cases, you can:

1. Limit the file scope first: git add -p src/components/
2. Use git add -i to enter interactive mode and then select patch
3. Set core.splitIndex to true to improve performance

Customizing Interactive Staging Behavior

You can customize interactive staging through Git configuration:

[interactive]
    singleKey = true  # Allow single-key responses
    diffFilter = "diff-highlight"  # Use highlighting for diffs

Equivalent Operations in GUI Tools

Most Git GUI tools provide similar functionality:

• VS Code: Click the + sign next to the line number
• GitKraken: Right-click the file and select "Stage Lines"
• SourceTree: Use "Stage Selected Lines"