Git Restore Explained with Examples (Files, Staged, Undo Changes)

What is Git Restore

Git restore is a modern Git command introduced to safely undo changes in your working directory or staging area without modifying commit history. It simplifies file-level operations like restoring modified files, unstaging changes, and recovering previous versions of files. Unlike git reset which works on commits, git restore focuses on restoring files.

What does git restore do

The git restore command helps you revert changes in files by restoring them to a previous state, typically from the last commit (HEAD). It can also unstage files or restore content from a specific commit or branch.

This makes it a safer and more intuitive alternative to older commands like git checkout command, especially when working with file-level changes.

When to use git restore

Use git restore when you want to:

• Undo changes in a file without affecting commit history
• Unstage files after using git add
• Restore a file from a previous commit or another branch
• Discard unwanted local changes safely

Git restore vs reset vs checkout

Git restore, reset, and checkout are often confused, but they serve different purposes:

• git restore → restores files (working directory or staging area)
• git reset → moves HEAD and modifies commit history
• git checkout → switches branches or restores files (older approach)

Git restore is preferred for file-level operations, while git reset is used for undoing commits. You can also compare workflows using git checkout command.

Git Restore Cheat Sheet

Git Restore Command Syntax

Basic syntax of git restore

The basic syntax of git restore is:

git restore [options] <file>

This restores the specified file to its previous state, typically from the last commit.

git restore --source usage

The --source option allows you to restore a file from a specific commit, branch, or reference.

git restore --source=<commit> file.txt

You can use commit references like HEAD~1 as explained in git HEAD caret vs tilde sign.

git restore --staged usage

The --staged option is used to remove files from the staging area without deleting changes from the working directory.

git restore --staged file.txt

This is equivalent to undoing git add.

git restore --worktree usage

The --worktree option restores changes only in the working directory, discarding local modifications.

git restore --worktree file.txt

This is useful when you want to discard changes without affecting the staging area. You can also explore git discard changes for similar use cases.

Git Restore Command Explained

git restore file

This command restores a specific file to its last committed state.

git restore file.txt

It is commonly used to discard unwanted changes in a file without touching other files.

git restore .

This restores all modified files in the current directory.

git restore .

Use this when you want to revert multiple file changes at once. Be cautious as it discards all local modifications.

git restore --staged

This command removes files from the staging area.

git restore --staged file.txt

It is useful when you accidentally staged files using git add. You can also refer to git undo add for similar scenarios.

git restore --source

This restores a file from a specific commit or branch.

git restore --source=HEAD~1 file.txt

It allows you to recover previous versions of a file without changing the entire branch history.

git restore --staged --worktree

This combination restores both staged and working directory changes.

git restore --staged --worktree file.txt

It completely resets the file to its last committed state. If you need to recover lost changes later, you can use git reflog command.

Common Git Restore Use Cases

Undo local changes in a file

If you have modified a file and want to discard those changes, you can restore it to the last committed state using:

git restore file.txt

This is one of the most common use cases of git restore, especially when you want to undo accidental edits without affecting other files. For broader cleanup scenarios, you can also refer to git discard changes.

Restore deleted file

If a tracked file is accidentally deleted from your working directory, you can recover it using:

git restore file.txt

Git will restore the file from the last commit. This is useful when you mistakenly remove files without committing the deletion.

Restore file to previous commit

To restore a file to a specific earlier version, use the --source option with a commit reference:

git restore --source=HEAD~1 file.txt

This allows you to retrieve older versions of a file without modifying the current branch history.

Unstage files using git restore

If you accidentally staged files using git add, you can unstage them using:

git restore --staged file.txt

This removes the file from the staging area while keeping changes in the working directory.

Restore all changes in repository

To discard all local changes across the repository and restore everything to the last committed state:

git restore .

This command restores all modified files in the current directory. Use it carefully as it will remove all uncommitted changes.

Restore changes after git pull

If a git pull introduces unwanted changes, you can restore files back to a clean state:

git restore .

This is helpful when resolving issues after merging remote changes. To understand pull behavior better, refer to git pull command and git fetch vs pull command.

Advanced Git Restore Scenarios

Restore file from another branch

You can restore a file from a different branch without switching branches:

git restore --source=branch-name file.txt

This is useful when you want to copy a file from another branch. You can explore branch-related operations as explained in git branch examples.

Restore specific version using commit hash

To restore a file from a specific commit using its hash:

git restore --source=<commit-hash> file.txt

This gives you precise control over file versions. You can inspect commit details using git show command before restoring.

Restore staged and working directory together

To completely reset a file in both staging and working directory:

git restore --staged --worktree file.txt

This ensures that all changes (staged and unstaged) are removed and the file matches the last commit.

Restore using patch mode

Patch mode allows you to selectively restore parts of a file instead of the entire file:

git restore -p file.txt

This is useful when you want fine-grained control over changes. You can combine this with insights from git diff command to review changes before restoring.

Common Errors and Fixes

git restore is not a git command

This error usually occurs when your Git version is older than 2.23, as the git restore command was introduced in Git 2.23.

Error:

git: 'restore' is not a git command. See 'git --help'.

Fix:

• Check your Git version:

git --version

• Upgrade Git to the latest version

Alternative: If upgrading is not possible, you can use older commands like git checkout command or git reset command to achieve similar functionality.

git restore not working

If git restore is not behaving as expected, common reasons include:

• File is not tracked by Git
• Incorrect file path
• Changes are already committed

Fix:

• Verify file status using:

git status

• Check differences using git diff command
• Ensure the file exists in the repository history

git restore not undoing changes

This usually happens when changes are already staged or committed. By default, git restore only affects the working directory.

Fix:

• If changes are staged:

git restore --staged file.txt

• If you want to discard working directory changes:

git restore --worktree file.txt

git restore fails for staged files

If git restore file.txt does not work for staged files, it is because the file is in the staging area.

Fix: First unstage the file:

git restore --staged file.txt

Then restore working directory changes:

git restore file.txt

This ensures both staging and working directory are reset properly.

Summary

Git restore is a powerful and safer alternative for undoing file-level changes in Git. It allows you to restore files, unstage changes, and recover previous versions without modifying commit history.

It is best suited for:

• Undoing local changes
• Restoring files from commits or branches
• Managing staging area efficiently

For commit-level operations, you should use git reset or git revert depending on your use case.

Further Reading

• Git Restore Official Documentation
• Git Reset Documentation
• Git Checkout Documentation
• Git Revert Documentation
• Git Official Documentation