git restore file resets a file's working directory to match a specific version in your Git history, such as the last commit or a branch state. It reverses local edits without affecting committed changes.
Git tracks changes to files over time. When you modify a file and don't commit those changes, they exist only in your working directory. git restore file lets you discard those uncommitted changes and return the file to its state in a previous commit or staging area.
This command is part of Git's newer, unified workflow introduced in Git 2.23. It replaces older commands like git checkout -- <file> and git reset HEAD <file>, which had inconsistent behavior depending on context.
When you run git restore file, Git checks the current state of the repository and applies the specified version of the file. By default, it restores from the index (staging area) or the most recent commit, depending on the options used.
For example, if you edited a file called config.json and accidentally saved broken JSON, running git restore config.json reverts the file to its last committed version. This action doesn't alter the commit history-it only changes the working directory.
The command operates on the filesystem level. It doesn't touch the Git object database or rewrite history. If you've made multiple edits since the last commit, git restore file discards all of them unless you specify a different source.
git restore file supports several flags to control which version of the file to restore:
--staged: Restores the file from the index (staging area).--worktree: Restores the file from the working directory (i.e., the current version).--source <commit>: Restores from a specific commit, branch, or tag.To restore a file from the last commit, use:
git restore --worktree config.jsonTo undo changes you've already staged, use:
git restore --staged config.jsonTo recover a file from a past commit, specify the commit hash:
git restore --source HEAD~1 config.jsonUsing --source allows you to pull a file from any point in history-even from a deleted branch-if you know the commit ID.
Suppose you're editing a Python script and realize you've overwritten a critical function. You haven't committed yet. Running git restore script.py returns the file to its state in the last commit.
If you've staged a file by mistake, use git restore --staged file.txt to remove it from the staging area. This is equivalent to git reset HEAD file.txt, but clearer in intent.
For a real-world example, imagine you're working on a web app and accidentally delete a JavaScript file. You notice the error after running git status. The file appears as "deleted" in the output. To recover it:
git log --oneline --all | grep filename.js to find the last commit that included the file.a1b2c3d).git restore --source a1b2c3d filename.js.The file reappears in your working directory.
git restore file does not delete commits or rewrite history. It cannot recover files that were never added to Git. If you modified a file but never ran git add, git restore file won't help-you must use a backup or file recovery tool.
It also doesn't replace git revert, which undoes a commit's effect by creating a new commit. git restore file only affects uncommitted changes. If you've already pushed changes, restoring locally won't fix remote branches.
A common confusion: git restore file doesn't update the current branch. It only changes the working directory. After running it, you still need to commit the restored file if you want to save the change.
Before Git 2.23, developers used git checkout -- <file> to restore uncommitted changes. That command was ambiguous because it also served to switch branches and restore files from the index.
git restore file clarifies intent. It separates actions into distinct operations:
| Action | Old Command | New Command |
|---|---|---|
| Discard working directory changes | git checkout -- file.txt | git restore --worktree file.txt |
| Unstage a file | git reset HEAD file.txt | git restore --staged file.txt |
| Restore from a commit | git checkout <commit> -- file.txt | git restore --source <commit> file.txt |
According to Git's official documentation, the new command structure improves clarity and reduces errors caused by misused flags (git-scm.com/docs/git-restore).
I once spent 20 minutes rewriting a configuration file during a deployment. I forgot to stage it before testing. After realizing the changes broke the build, I ran git restore --worktree config.yaml. The file reverted instantly. I'd lost nothing. The command saved me from a late-night rollback.
This experience highlighted how important it is to understand the difference between staging and working directory states. git restore file makes that distinction explicit.
Always verify the file state before running git restore file. Use git diff to see what changes remain. Run git status to confirm whether the file is staged or unstaged.
Never run git restore file on a file you've already committed and pushed. That action may cause conflicts later. Instead, use git revert or git reset if you need to undo a published change.
For teams, document the use of git restore file in your workflow guide. New contributors often expect it to behave like git reset, leading to unintended side effects.
As a rule, if you're unsure, test the command on a copy of the file first. Git doesn't require you to back up your work-but doing so manually is safer than relying on memory.
git restore file is a precise tool for recovering uncommitted changes. It's not a substitute for good habits like regular commits, clear messages, and reviewing diffs. But when you make a mistake, it's a reliable way to get back to a known state.