How do Git restore options differ for staged and unstaged changes?

Think of the index (staging area) and working tree (the file you edit) as two different states. A restore command targets one or both:

• git restore --staged <path> restores the index entry from HEAD by default. It removes that path’s staged difference but leaves working-tree edits in place.
• git restore <path> restores the working-tree file from the index by default. It can discard edits that exist only in the working tree.
• git restore --staged --worktree <path> restores both locations. [S1]

For example, if notes.txt has changes in both states, the first command targets its staged difference; the second targets its unstaged working-tree difference. Use the path you intend to affect.

Check status and the relevant diffs before running a restore:

git status --short
git diff --cached -- notes.txt
git diff -- notes.txt

The cached diff compares staged changes with HEAD; the regular diff compares working-tree changes with the index. They show distinct states, so review the one—or both—that your planned command will affect. [S2]

If both diffs show changes for notes.txt, git restore --staged -- notes.txt targets the staged difference, while git restore -- notes.txt targets the unstaged working-tree difference. [S1] Check the path carefully, and pause to read the options if you are unsure what a command will change.

If your goal is to remove the file’s staged difference while retaining its current working-tree edits, inspect both diffs first. Then run:

git restore --staged -- notes.txt

Replace notes.txt with the path you intend. By default, this restores the index entry from HEAD and leaves the working-tree edits in place. [S1]

Afterward, check git status --short, git diff -- notes.txt, and, if useful, git diff --cached -- notes.txt. These checks show the resulting states; they are not a guarantee that edits discarded by another operation can be recovered. [S2]

Choose based on which state you want to change and what you want it restored from:

• To make the working-tree file match the index, use git restore -- <path>. This can discard unstaged edits. [S1]
• To remove staged changes while keeping working-tree edits, use git restore --staged -- <path>. [S1]
• To restore both the index and working tree, use git restore --staged --worktree -- <path>. [S1]

Before any of them, review git status --short, git diff --cached -- <path> for staged changes, and git diff -- <path> for unstaged changes. [S2] Confirm the path is exactly the one you intend, then inspect status and diffs afterward. The diffs help identify the states affected, but do not guarantee recovery of edits discarded by a restore. [S2]