How to unstage changes in Git

A staged change can be ready for the wrong commit even though the file on disk still needs more review. Unstaging moves the selected path out of Git's index without deleting the working-tree edit, so the next commit can be narrowed before any content is thrown away.

git restore –staged copies the version from HEAD back into the index for the named path. The working-tree file is left alone, which is why git status –short changes from M docs/notes.md to M docs/notes.md after the path is unstaged.

Use this when git add staged too much, partial staging needs to be redone, or a file belongs in a later commit. It is not the command for discarding edits; review git diff –cached before running it and use git diff afterward to confirm the edit remains on disk.

1. Open a terminal in the repository that contains the staged change.
2. Check the current staged state.

   $ git status --short
   M  docs/notes.md

   In short status output, the left column is the index and the right column is the working tree. M docs/notes.md means the file is staged and has no additional unstaged edit.

3. Review the staged content before moving it out of the index.

   $ git diff --cached -- docs/notes.md
   diff --git a/docs/notes.md b/docs/notes.md
   index 5cfa7fc..adc66fb 100644
   --- a/docs/notes.md
   +++ b/docs/notes.md
   @@ -1,3 +1,5 @@
    # Release notes
    
    Initial checklist
   +
   +- update deployment checklist

   git diff –cached shows the staged version compared with HEAD. The output should be the change that needs to leave the next commit.

4. Unstage the selected path.

   $ git restore --staged -- docs/notes.md

   No output means Git updated the index without conflicts. The -- separator keeps the following argument interpreted as a file path.

   Use git restore --staged . from the repository root only when every staged path should be moved out of the index.

5. Confirm that the path is no longer staged.

   $ git status --short
    M docs/notes.md

   The leading space and right-column M mean docs/notes.md is now only a working-tree modification. The edit is still on disk, but it is no longer part of the next commit.

6. Confirm that the staged diff for the path is empty.

   $ git diff --cached -- docs/notes.md

   No output means the index copy of docs/notes.md matches HEAD.

7. Confirm that the working-tree edit remains.

   $ git diff -- docs/notes.md
   diff --git a/docs/notes.md b/docs/notes.md
   index 5cfa7fc..adc66fb 100644
   --- a/docs/notes.md
   +++ b/docs/notes.md
   @@ -1,3 +1,5 @@
    # Release notes
    
    Initial checklist
   +
   +- update deployment checklist

   This final diff is the success check for an unstage operation: the change is absent from the index and still present in the working tree. Related: How to discard file changes with git restore