Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 78 ยท The Basic Workflow

Staging Changes: add, patch Mode and Partial Commits

Learn how the Git staging area works: git add variants, git add -p for partial commits, unstaging with restore, intent-to-add and the three versions of a file.

Most version control tools have one step: "save my changes". Git has two. First you stage the changes you want, then you commit what is staged. The staging area (also called the index) sits between your working directory and the history, and it is the single most misunderstood part of Git for beginners and the most loved part for experts.

Why would you want a middle step? Because real work is messy. You fix a bug, notice a typo in a different function, and add a debug print, all in one afternoon. If every save were a commit, your history would be a pile of unrelated changes. With staging you decide exactly what goes into the next snapshot, so each commit tells one clear story. This lesson shows how git add works in all its forms, how to stage only part of a file with git add -p, and how to take things back out again. If the three areas are new to you, read How Git Works first.

The staging area is a drafting table

Picture a photographer preparing a group photo. The people wandering around the room are your working directory: they move, change clothes, come and go. The staging area is the set of people standing on the stage, lined up for the shot. The commit is the photograph, which never changes once taken.

TEXT
 working directory          staging area (index)            repository
 โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  git add  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  git commit  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
 โ”‚ files you editโ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ถ โ”‚ next snapshot โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ถ โ”‚ saved historyโ”‚
 โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜           โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜              โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
         โ–ฒ                           โ”‚
         โ””โ”€โ”€โ”€โ”€ git restore โ—€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜   (git restore --staged goes back one step)

The index is a real file, .git/index, that holds a list of paths with the exact content (as blob IDs) that the next commit will contain. When you run git commit, Git does not look at your working directory at all. It turns the index into a snapshot. This is why editing a file after git add does not change what gets committed, as the next example shows.

Bash Add, then edit again: two different comparisons

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The status codes use two columns: the left one compares the index with the last commit, the right one compares the working tree with the index. After the first git add, the file shows A (added to the index, working tree matches). After the second edit it shows AM: added to the index, and modified again since. The two git diff commands answer the two questions separately. Plain git diff shows only the second line (+two), because the first line is already staged. git diff --staged shows what the next commit will contain: the file with just one. See Status, Diff and Seeing Changes for how to read these outputs in depth.

The forms of git add

git add is one command with several meanings, depending on what you give it.

Command What it stages
git add file.txt That file (new, modified or deleted)
git add dir/ Everything under dir/
git add . Everything in the current directory and below
git add -u Modifications and deletions of files Git already tracks; never new files
git add -A Everything in the whole repository: new, modified, deleted
git add -p Chosen pieces of files (patch mode, see below)
git add -N file Only a note that the file will exist (intent to add)

Since Git 2.0, git add . and git add -A behave the same when run from the top of the repository, including staging deletions. The difference is scope: . means "this directory and below", while -A always means the whole working tree, even when you run it from a subdirectory.

Bash Comparing add -u and add -A

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

We changed one file, deleted one and created one. git add -u staged the modification (M) and the deletion (D) but left new.txt as untracked (??), because -u only touches files Git already knows. git add -A staged all three. The git reset -q in the middle just emptied the index again so we could compare fairly (more on that in Undoing Things).

Which one should I use? Use git add -A or git add . when you really did intend to commit everything. Use git add -u when you edited tracked files and do not want stray new files (logs, build output, scratch notes) to sneak in. Use explicit paths when you want to be sure. Whichever you choose, run git status before you commit. Files you never meant to track belong in .gitignore.

Deleted and renamed files

git add also records deletions: if you remove a file from the working tree, git add -A or git add -u stages the removal. You can also use git rm to delete and stage in one step. Git does not store renames explicitly; it notices that a deleted path and a new path hold the same content. See Moving, Renaming and Removing Files.

Patch mode: stage pieces, not files

Sometimes a single file contains two unrelated changes. git add -p (or --patch) walks through your changes hunk by hunk and asks what to do with each one. Whatever you accept goes into the index; the rest stays in your working tree as an unstaged change.

A hunk is a contiguous block of changed lines plus a few lines of context around it, exactly what you see in a unified diff. In the next example we change line 2 (a real bug fix) and line 28 (a debug print that must not be committed). They are far apart, so Git sees two hunks.

Bash Staging one hunk with add -p

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

In a real terminal git add -p is interactive. For each hunk it prints the diff and a prompt such as Stage this hunk [y,n,q,a,d,s,e,?]?. Here we feed the answers through a pipe (y then n) and hide the prompt text with > /dev/null, so only the results show. Notice what happened: git diff --staged contains only the bug fix, git diff still shows the debug print, and after the commit the debug line remains as a leftover modification ( M). The commit 6f95461 contains the fix and nothing else. (The hash is the same on every run because we fixed the author, committer and dates.)

These are the answers you can give at the prompt:

Key Meaning
y / n Stage / do not stage this hunk
q Quit; do not stage this hunk or any later one
a / d Stage / skip this hunk and all remaining hunks in the file
s Split the hunk into smaller hunks (only works if there are unchanged lines between changes)
e Edit the hunk by hand, for changes that are too tangled to split
g / / Jump to a hunk / search for a hunk by regex
? Print help

If two changes sit on neighboring lines, Git shows them as one hunk and s cannot separate them. Then use e to open the patch in your editor: delete the + lines you do not want (or turn - lines you want to keep into plain context lines by replacing the - with a space). It takes practice, but it lets you stage any subset of changes.

git add -p only offers files Git already tracks. A brand-new file has no previous version to compare to. To stage part of a new file, first run git add -N file (below) and then git add -p file.

The same patch interface exists in other commands. git restore -p discards chosen hunks from your working tree, git restore --staged -p unstages chosen hunks, git stash -p stashes only some changes, and git checkout -p and git reset -p do older variants of the same. Once you know the prompt, you know all of them.

One file, three versions

A subtle but central fact: a tracked file that has been edited and staged can exist in three different versions at once: the one in the last commit (HEAD), the one in the index, and the one in your working directory. Git has a notation to look at each of them.

Bash HEAD, index and working tree can all differ

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

git show HEAD:f.txt prints the committed version, and git show :f.txt (a colon and a path) prints the index version. The status code MM means "modified in the index, and modified again in the working tree". When we commit, only v2 (the staged content) is saved. The v3 edit survives in the working directory as a normal unstaged modification. Beginners are often surprised by this: "I saved the file, why did the commit not include it?" The answer is almost always that they edited after git add.

Taking things out of the index

You staged too much. How do you unstage? Since Git 2.23 the clear answer is git restore --staged:

TEXT
git restore --staged file.txt    # index goes back to HEAD; your working file is untouched

This copies the HEAD version of the file into the index, leaving your edits in the working directory. Older tutorials use git reset HEAD file.txt, which does the same thing and still works. Be careful not to confuse it with git restore file.txt (no --staged), which overwrites your working file with the staged version and throws your unsaved edits away. The undo lesson has a full decision table.

Intent to add

Normally a brand-new file is invisible to git diff until you stage it, because it is untracked. git add -N (--intent-to-add) puts an empty placeholder in the index so the file becomes "tracked" and its full content shows up as an unstaged change.

Bash Unstage with restore, then use intent-to-add

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Unstaging the modified a.txt leaves its edit in place ( M). Unstaging the new b.txt makes it untracked again (??), because it never existed in HEAD. After git add -N b.txt the status shows A: the right column says "added in the working tree only", and git diff now prints the whole file as new content. That is exactly what you need before git add -p b.txt, and it is also handy for reviewing a new file with git diff before committing it.

Committing only part of your work

Now you can combine everything into a habit that produces clean history:

  1. Make all the edits you need, even unrelated ones.
  2. Run git status and git diff to see what you have.
  3. Stage one logical change at a time: whole files with git add path, partial files with git add -p.
  4. Check what is staged with git diff --staged.
  5. Commit with a good message (see Making Good Commits).
  6. Repeat for the next change.

Step 4 is the one people skip and later regret. It is the last chance to see exactly what the snapshot will contain. A good alias or habit is to run git diff --staged --stat for a summary and git diff --staged for the details before every commit.

Pitfalls professionals know

  • Staging is per content, not per filename. If you git add and then edit, the index keeps the older content. Re-run git add or you commit stale content.
  • git add . is not "safe". It stages secrets, large binaries and build output just as happily as source code. Keep a good .gitignore and read git status.
  • Partial commits are not tested commits. When you commit only some hunks, the committed state is a combination your working tree never had. It may not compile. Professionals check with git stash --keep-index (see Stashing) to test the staged state alone.
  • Never edit files while add -p is running. The hunks were computed when it started.
  • Empty directories cannot be staged. Git tracks files, not folders; put a placeholder file such as .gitkeep in a directory you want to keep.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You run git add notes.txt and then edit notes.txt again before committing. What does the commit contain?

    A commit is built from the index, not from the working directory. The second edit stays as an unstaged change until you run git add again.
  2. 2. Which command stages deletions and modifications of tracked files but ignores brand-new files?

    git add -u (--update) only touches paths that are already tracked. -A and . also stage untracked files.
  3. 3. What does the s answer do at a git add -p prompt?

    s splits a hunk. If the changes touch adjacent lines it cannot split them, and you need e (edit) instead.
  4. 4. How do you unstage a file but keep your edits in the working directory?

    git restore --staged resets the index entry to HEAD and leaves the working file alone. Plain git restore would overwrite your working file.
  5. 5. What does the status code MM mean?

    The first column compares the index with HEAD and the second compares the working tree with the index. M in both means the file has staged changes and further unstaged changes.

Summary

  • The index (staging area) holds the exact content of the next commit; git commit ignores the working directory.
  • git add path stages that path, -u stages only tracked files, -A stages everything, -N records an intent to add.
  • git add -p stages hunk by hunk; answer y, n, s, e, q, a or d, and use e for tangled changes.
  • A file can differ in HEAD, the index and the working tree; git show :file reads the index version.
  • git restore --staged unstages without losing edits; plain git restore discards edits.
  • Review with git diff --staged before every commit.

Next: Making Good Commits