The Git Staging Area Explained: git add and git restore

Why does Git need two steps, add and commit? Because you often change several things at once but want to save them as separate, clear commits. The staging area lets you choose exactly what goes into each one.

The three areas#

Working tree        Staging area         Repository
(your files)        (next commit)        (saved history)

    edit  -- git add -->       -- git commit -->

• The working tree is the files you see and edit.
• The staging area (also called the index) is a draft of the next commit.
• The repository is the history of commits in .git.

Splitting work into two commits#

Suppose you have a project with two files, and you fix a typo in one while adding text to the other:

echo "Home page, updated" > index.txt
echo "Contact: hello@example.com" >> about.txt
git status --short

 M about.txt
 M index.txt

--short gives a compact view. M means modified but not staged. Stage only one file:

git add index.txt
git status --short

 M about.txt
M  index.txt

M (with the M in the left column) means staged. The left column is the staging area and the right column is the working tree. Commit just that file:

git commit -q -m "Update home page text"
git status --short

 M about.txt

The other change is untouched, ready for its own commit:

git add about.txt
git commit -q -m "Add contact email"
git log --oneline

e75357f Add contact email
310df11 Update home page text
2963a66 Add first pages

Now each commit does one thing, which makes history easier to read and easier to undo.

Unstage a file#

If you stage something by mistake, take it off the list. Your edits stay in the file:

echo "Draft text" >> about.txt
git add about.txt
git restore --staged about.txt
git status --short

 M about.txt

Stage part of a file#

If one file contains two unrelated changes, git add -p shows each change (a "hunk") and asks what to do with it:

git add -p notes.txt

Answer y to stage a hunk, n to skip it, s to split it into smaller hunks, and q to stop.

Staged content is a snapshot#

git add copies the file as it is at that moment. If you edit again afterwards, the new edit is not staged:

echo "Line one" >> index.txt
git add index.txt
echo "Line two" >> index.txt
git status --short

MM index.txt

MM means there are staged changes and also newer unstaged ones. Run git add again to include the latest version.

Removing and renaming files#

Use Git's commands so that the change is staged for you:

git rm about.txt
git mv index.txt home.txt
git status --short

rm 'about.txt'
D  about.txt
R  index.txt -> home.txt

D is deleted and R is renamed. Git has no special record for a rename: it notices that a new file has the same content as a deleted one.

To stop tracking a file but keep it on disk, for example one you committed by mistake:

git rm --cached secret-notes.txt

Common mistakes#

Practice#

git add a.txt b.txt
git restore --staged b.txt
git status --short

M  a.txt
 M b.txt

Key takeaway#

Next: Viewing History with git log.