git restore

Basic Snapshotting

Restore files in the working tree or the staging area


The 'git restore' command puts files back to a known version. By default it overwrites a working file with its staged version, discarding your edits. With --staged it takes a file out of the staging area and keeps your edits on disk. With --source you can bring back a file as it was in any commit. It was added in Git 2.23 to take over the file-restoring half of git checkout.

Synopsis

git restore [<options>] [--source=<tree>] [--staged] [--worktree] [--] <pathspec>...
[ ] optional| or<arg> placeholder... repeatable--flag option

Options

Click any option to expand

Beginner (2)

Restore the staging area: unstage the file. Your working file is not touched.

RecommendedThe safe way to unstage: your edits stay on disk

Example

git restore --staged app.js

Restore the working tree (the default). Combined with --staged, both are restored.

When neededDefault target; combine with --staged to reset both

Example

git restore --staged --worktree app.js

Intermediate (2)

Take the file from the given commit, branch or tag instead of the staging area.

RecommendedRecover one file from any commit without moving the branch

Example

git restore --source=HEAD~1 app.js

Choose hunks interactively: git asks about each change.

When neededDiscard selected hunks and keep the rest

Example

git restore -p app.js

Choosing the Right Option

restore vs older commands

The same actions, old and new

CommandOlder equivalentEffect
git restore app.jsgit checkout -- app.jsDiscard unstaged edits
git restore --staged app.jsgit reset app.jsUnstage, keep edits
git restore --source=HEAD~1 app.jsgit checkout HEAD~1 -- app.jsFile from an old commit

Examples

Discard edits

git restore app.js

Throw away the changes in app.js that are not staged.


Unstage a file

git restore --staged app.js

Take app.js out of the staging area, keep the edits.


File from an old commit

git restore --source=HEAD~2 app.js

Get app.js as it was two commits ago.

Workflow Examples

1
git add .

Everything is staged

2
git restore --staged README.md

README.md is unstaged

3
git commit -m "Add to cart"

The commit leaves README.md out

Troubleshooting

error: pathspec 'x' did not match any file(s) known to git

Cause: The file is untracked or the path is wrong

Check the path with git status; restore only works on tracked files

I restored a file and lost my edits

Cause: git restore overwrites the working file

Unsaved edits are gone; your editor undo history may still have them. Next time, git stash first

Tips & Pitfalls

Best Practices

  • ✓Run git diff before git restore to see what you are about to throw away.
  • ✓Use git restore --staged to unstage — it never touches your edits.
  • ✓Prefer git restore over git checkout for files: its name says what it does.

Common Mistakes

  • ✗Running git restore <file> on edits you wanted to keep — discarded edits cannot be recovered.
  • ✗Expecting git restore --staged to discard your edit: it only unstages it.
  • ✗Using git restore to undo a commit — it restores files; use git reset or git revert for commits.

FAQ

A:

git restore changes files. git reset moves the branch to another commit (and can reset files too).

A:

Not for discarded working edits: Git never stored them. Unstaging with --staged loses nothing.

A:

Git 2.23 or newer. On older versions use git checkout -- <file> and git reset <file>.