Unstage a file

Sometimes the index contains a file you do not want in the next commit. Maybe you ran git add . and it swept in a file that belongs to a different change, or you staged an experiment you are not ready to record. Unstaging changes the index, not the working file, so your edits are never at risk.

Inspect the current state first:

git status
git diff --staged -- README.md

git status lists the file under “Changes to be committed”, and the staged diff shows exactly what would enter the commit. Notice that git status already prints the answer in its hint line: “use git restore —staged … to unstage”.

Then unstage the file:

git restore --staged README.md

By default, Git restores the index entry from HEAD, the current commit. In plain words: the staging area’s copy of README.md goes back to matching the last commit, as if you had never run git add on it. Your edited README.md stays in the working tree, untouched.

Verify both states:

git status
git diff -- README.md
git diff --staged -- README.md

The ordinary diff now shows the edit. The staged diff no longer does. The file moved from “Changes to be committed” to “Changes not staged for commit”.

This is a recoverable action because the working content remains available. It is different from git restore README.md, which targets the working tree and can overwrite unstaged content permanently. The --staged flag is the whole difference between a safe command and a destructive one, so read twice before pressing Enter.

You may also see git reset HEAD README.md in older tutorials. It has the same effect; git restore --staged is the clearer modern spelling of the same operation.

Exercise: stage two files, unstage one, and predict exactly which file the next commit will contain. Then run git commit and check the result with git show --stat.