git restore

Modern, intent-clear replacement for half of git checkout.

🎯 What & why

Modern, intent-clear command for undoing changes in the working tree or index. Replaces the half of git checkout that handled file restoration. New in Git 2.23, recommended since.

🧠 Mental model

Restore touches paths, not refs. The --source option says where to copy from (defaults to HEAD or the index). --worktree (default) writes to the working tree. --staged writes to the index. Combine flags to do both.

🛠️ Synopsis

git restore [<options>] [--source=<tree>] [--staged] [--worktree] [--] <pathspec>...
git restore (-p|--patch) [<options>] [--source=<tree>] [--staged] [--worktree] [--] [<pathspec>...]

🎚️ Switches & options

Flag	What it does
`--source=<tree>`	Take the file content from `<tree>` (commit, branch, tag). Default: index for working tree, HEAD for index.
`--staged, -S`	Restore the index. Effectively unstages.
`--worktree, -W`	Restore the working tree (default).
`-p, --patch`	Pick hunks to restore.

💡 Use cases

Undo unstaged edits without affecting other files.
Unstage with intent ('I added too much, back it out').
Pull a file from any historical state without checking out a different branch.

🧪 Examples

Throw away unstaged changes to a file.

$ git restore src/main.c

Unstage a file (keep your edits).

$ git restore --staged src/main.c

Unstage and discard the working-tree changes.

$ git restore --staged --worktree src/main.c

Bring back a file from a different commit.

$ git restore --source=HEAD~2 -- README.md

🎓 Recommendations

Prefer restore over checkout -- <path>. Same effect, clearer intent. Tooling and docs are moving this way.
Pair with git status after every restore — confirm what's left.

🪤 Common pitfalls

git restore <path> is destructive of unstaged changes. There is no undo (the changes were never in the index).
Without --staged, a restore won't unstage — you'll be confused why your git status still shows staged changes.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.