Staging & Committing Precisely

In one line

git add doesn't have to mean 'the whole file' — git add -p lets you stage individual chunks of a change, and git diff shows you exactly what you're about to commit before you commit it.

0/4 · 0%

Think of it like this

Editing a single paragraph in an essay but only wanting to submit half of your edits for now — git add -p (patch mode) is exactly this: it walks through your changes chunk by chunk (called HUNKS), asking 'stage this piece? yes/no/split further' for each one, rather than forcing an all-or-nothing choice per file.

Key ideas

01
git diff (with nothing staged) shows the difference between your WORKING DIRECTORY and the last commit — exactly what you've changed but haven't yet staged. git diff --staged (or --cached) shows the difference between what's STAGED and the last commit — exactly what your next commit will actually contain. Confusing these two is a genuinely common source of 'wait, why didn't that change get committed' surprises.
02
git add -p <file> splits a file's changes into hunks and lets you stage them individually — y stages the current hunk, n skips it, s tries to split it into smaller hunks if possible, and q quits. This is the tool for the exact scenario from Phase 0.2: multiple unrelated changes sitting in one file, only some of which belong in this commit.
03
git restore <file> (introduced in Git 2.23, replacing the more confusing overloaded uses of checkout for this purpose) discards UNSTAGED changes in the working directory, restoring the file to match the last commit — genuinely destructive for that file's uncommitted edits, so it's worth a git diff first to confirm exactly what you're about to lose.
04
git restore --staged <file> UNSTAGES a file without touching its actual content in the working directory — the file's edits are still there, just moved back out of the staging area, exactly undoing what git add did. This is the correct fix for 'I accidentally staged the wrong file.'
05
A genuinely good habit: run git diff --staged right before every git commit, as a final review of EXACTLY what's about to become permanent history — catching a leftover debug line or an accidentally staged unrelated file here costs seconds, versus needing Phase 5's history-rewriting tools to fix it after the fact.

Code & diagrams

staging-precisely.shmarkdown

Practice on a file with two clearly separate changes.

cd ~/scratch/my-first-repo

# Make two unrelated changes to the same file
echo "Real fix: corrected the calculation" >> notes.txt
echo "DEBUG: remove before committing" >> notes.txt

# See exactly what's different from the last commit
git diff notes.txt

# Stage interactively, hunk by hunk
git add -p notes.txt
# For each hunk: y = stage it, n = skip it, s = split further, q = quit

# Confirm EXACTLY what's about to be committed
git diff --staged

# Made a mistake? Unstage without losing the edit
git restore --staged notes.txt

# Discard an edit entirely (destructive — confirm with diff first)
git diff notes.txt
git restore notes.txt

Explain it without notes

What's the practical difference between git diff and git diff --staged, and when would you use each?

You accidentally ran git add on the wrong file. What's the correct command to undo just that, without losing the file's actual edits?

Practice

Make two separate, unrelated edits within the same file and use git add -p to stage only one of them, confirming with git diff --staged that only the intended change is staged.

Stage a file, then use git restore --staged to unstage it, and confirm with git status and git diff that your actual edits are still sitting, intact, in the working directory.

Trade-offs

↔
Patch-mode staging produces genuinely cleaner, more reviewable commits, but it takes real extra time and discipline compared to a blanket git add . — for quick, low-stakes personal projects that overhead may not be worth it, but for anything reviewed by teammates, a clean, single-purpose commit is almost always worth the few extra seconds it costs to build deliberately.

Done when you can

I can use git diff and git diff --staged and know which one to check before committing.
I can stage part of a file's changes using git add -p.
I know git restore --staged undoes a git add without losing my actual edits.