Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git Staging Area: status, add -p, commit --amend, and Partial Commits

The index is what a commit actually contains, which makes partial commits possible and commit -a dangerous. What amend rewrites, and when that is safe.

~4 min readGit
#Git#Commit#Staging#CLI
3D illustration of file cards moving through working, staging and commit trays

Quick Summary

Git has three places a change can live: the working tree, the index (staging area), and the commit history. git status compares all three; git add copies content from the working tree into the index; git commit turns the index into a commit. Nothing about a commit depends on the working tree — what you staged is exactly what gets committed, even if the file changed again afterwards.

That is the mechanism behind partial commits: stage one hunk, commit it, and the rest of the file stays uncommitted. git add -p is the tool for it, and git restore --staged is the undo.

git commit --amend replaces the previous commit rather than editing it — a new commit with a new hash, the old one left in the reflog. That is harmless before a push and a rewrite after one.

Basic Syntax & Core Signatures

bash
# Inspect git status git status -sb # short format with branch and ahead/behind git status --porcelain=v2 # stable machine-readable output for scripts git diff # working tree vs index git diff --staged # index vs HEAD (alias: --cached) git diff HEAD # working tree vs HEAD # Stage git add file.txt git add -A # everything, including deletions, from repo root git add -u # tracked files only: modifications and deletions git add . # current directory and below (respects .gitignore) git add -p # hunk by hunk git add -N newfile.txt # intent-to-add: diff shows it, content not staged git add -f build/output.bin # override .gitignore # Commit git commit -m "feat: add retry budget" git commit -m "fix: handle empty payload" -m "Refs: APP-142" git commit -am "chore: bump deps" # add -u then commit in one step (tracked only) git commit --amend --no-edit # add staged changes to the last commit, keep message git commit --amend -m "new message" git commit --fixup=HEAD # commit that autosquashes later git commit --allow-empty -m "chore: trigger ci" git commit --no-verify # skip hooks, for emergencies only # Unstage and restore git restore --staged file.txt # unstage, keep working tree changes git restore file.txt # discard working tree changes git restore --source=HEAD~2 file.txt

git commit -a is not git add . && git commit: it only sees tracked files, so a new file is silently left out. That is why the pattern "commit -am" misses the file you just created.

Key Comparison Table

CommandNew filesModificationsDeletionsScope
git add -AYesYesYesWhole repository
git add -uNoYesYesWhole repository
git add .YesYesYesCurrent directory and below
git add -pNo, only tracked hunksYes, selectableVia promptInteractive
git commit -amNoYesYesWhole repository
Status codeMeaningTypical next step
M Modified and stagedgit commit
MModified, not stagedgit add -u
MMStaged, then modified againgit add to include the newer change
A Added to the indexgit commit
D / DDeleted and staged / deleted, not stagedgit add -u to stage the deletion
??Untrackedgit add if it belongs, else .gitignore
UUUnmerged, conflict presentResolve, then git add

Practical Edge Cases & Deep Dives

1. Splitting one file into two commits

Editing a file for two unrelated reasons is normal; committing them together is what makes review and revert painful. git add -p walks hunks and offers y/n/s/e; s splits a hunk, e opens the hunk in an editor for line-level selection.

bash
git add -p src/handler.ts # stage only the bug fix hunks git commit -m "fix: guard against missing id" git add -p src/handler.ts # stage the refactor hunks git commit -m "refactor: extract parse step"

If the two changes are on adjacent lines Git cannot split them, and e is the only way through. Editing the hunk means deleting the + lines you do not want; the index keeps the rest while the working tree keeps everything.

2. Amending safely, and what it does to history

--amend builds a new commit from the current index plus the old commit's parent. The old commit stays reachable through HEAD@{1} until garbage collection. Before a push, that is a clean way to fix a message or fold in a forgotten file. After a push to a shared branch, it means every colleague's main diverges.

bash
git add forgotten.ts git commit --amend --no-edit git push --force-with-lease origin feature/x # only if the branch is yours

--amend does not change the author date; the committer date becomes now. That is why a rebased or amended history shows old author dates with new committer dates.

3. --fixup and --autosquash as the review-friendly path

Instead of amending, commit a fix tagged to the commit it belongs to. The history stays linear and the squash happens at rebase time:

bash
git commit --fixup=3f2a1b9 # message becomes "fixup! <original subject>" git commit --squash=3f2a1b9 # keeps the message for editing during rebase GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash origin/main

GIT_SEQUENCE_EDITOR=: accepts the generated todo list without opening an editor, which makes the whole operation scriptable in CI or a pre-push hook.

4. Staging a deletion while keeping the file

git rm --cached removes a path from the index but leaves the file on disk, which is the correct way to start ignoring a file that was committed by mistake. Combined with .gitignore, it stops tracking without deleting:

bash
git rm --cached .env.local printf '\n.env.local\n' >> .gitignore git commit -m "chore: stop tracking local env file"

The file stays in history. If it contained a secret, rotate the secret; rewriting history does not un-leak it.

5. Pathspec commits that bypass the index

git commit path/to/file commits the working-tree content of those paths even if the index holds something else for them, and it leaves the index untouched. Useful for a one-line hotfix while a large refactor sits staged; confusing when you expected the staged version to be committed:

bash
git commit -m "hotfix: null check" src/parse.ts git status # the staged refactor is still staged

6. status in scripts and submodules

Parsing git status output is fragile; --porcelain=v2 -z is the stable interface. In a repository with submodules, git status reports a modified submodule as a single line regardless of how many files changed inside it, and git add submodule stages the recorded commit, not the contents. Use git submodule foreach when the change must be committed inside each submodule first.

A second scripting trap is the exit code. git status returns 0 whether or not the tree is clean, so a script that checks if git status; then always takes the clean path. Use git diff --quiet and git diff --cached --quiet to test for unstaged and staged changes, and git status --porcelain | grep -q . when untracked files matter too:

bash
if ! git diff --quiet || ! git diff --cached --quiet; then echo "dirty" fi

Common Git Operation Mistakes

SymptomCauseFix
New file missing from the commitgit commit -am usedgit add the file, then commit
Commit contains more than intendedgit add . from the repo rootgit add -p, or git restore --staged the extras
Deleted file still trackedgit add . run from a subdirectory, or -u not usedgit add -A from the root
Amended commit duplicated in the remote--amend after a push--force-with-lease, and tell colleagues
.env committed and pushed.gitignore added after the file was trackedgit rm --cached, rotate the secret
Staged change did not make it into the commitPathspec commit usedCheck git status for what is still indexed
Hook blocks every commitPre-commit hook failing on unrelated filesFix the hook, do not make --no-verify the habit
Index looks empty after a mergeMerge state present, index holds the mergeFinish with git commit or git merge --abort
Commit went to the wrong branchswitch failed silently in a scriptUse git switch -c name and check git branch --show-current

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.