Interactive Staging

One-liner

git add -p stages changes hunk by hunk, letting you craft focused commits from a messy working directory.

Why it matters

After a work session, your working directory often contains multiple unrelated changes: a bug fix, a refactoring, and a new feature. Committing everything together makes history useless — you can't revert one change without reverting all. Interactive staging lets you separate concerns into distinct commits, each telling one clear story.

Core concept

Imagine you wrote three letters on the same piece of paper. Before mailing them to three different people, you need to photocopy specific paragraphs onto separate sheets. git add -p is that photocopier — it shows you each paragraph (hunk) and asks "which letter does this belong to?" You sort changes into logical groups without touching the original paper.

The working directory stays unchanged. You're only choosing what goes into the next commit.

How it works

1. Run git add -p — git presents each diff hunk with a prompt.
2. Decide per hunk — y (stage), n (skip), s (split into smaller hunks), e (manually edit the hunk).
3. Split when needed — if two unrelated changes are adjacent in a file, s breaks them apart for individual staging.
4. Edit for precision — e opens the hunk in your editor for line-level control over what's staged.
5. Commit and repeat — commit the staged subset, then git add -p again for the next logical group.

Key terms

• Hunk — a contiguous block of changed lines that git presents as a unit
• Stage/Index — the area between working directory and commit; git add -p selectively fills it
• y/n/s/e/q — stage, skip, split, edit, quit — the core interactive commands
• git diff --cached — shows what's currently staged (helps verify before committing)
• git reset -p — the reverse: interactively unstage hunks you staged by mistake

Common misconceptions

• "You have to commit all changes in a file together" — git add -p lets you stage individual hunks or even individual lines within a file. One file can contribute to multiple commits.
• "Splitting changes is a waste of time" — The 2 minutes spent curating saves hours of confusion later in reviews, reverts, and bisects.
• "You need special tooling" — git add -p works in any terminal. No IDE required, though many IDEs expose the same functionality graphically.

When to use / not use

✓ Use when: your working directory has multiple logical changes, you want clean atomic commits, you're preparing a PR for review, or you need to commit a fix without including unrelated work.

✗ Don't use when: all changes belong to the same logical unit (just git add .), you're working on a throwaway branch where history doesn't matter, or you'll squash everything later anyway.

Example

# Stage changes hunk by hunk
git add -p

# Verify what's staged vs what remains
git diff --cached --stat   # staged (next commit)
git diff --stat            # unstaged (stays for later)

# Commit the curated subset
git commit -m "fix(auth): validate email format"

Next steps

1. Build the habit: never use git add . for multi-concern changes — always git add -p
2. Learn the e (edit) mode for line-level precision when s (split) isn't granular enough
3. Combine with git stash push -p to selectively stash only certain hunks for later