Table of contents

• What is git restore?
• Using git restore
• git restore in branch management
• Best practices using git restore
• Frequently asked questions

What is git restore?

git restore is a command used to restore files in the working directory or the staging area (index) to their last committed state. Introduced in Git version 2.23.0, git restore was added to the Git CLI as part of the effort to split the overloaded responsibilities of git checkout into more focused and intuitive commands. This command helps manage changes by selectively discarding edits or un-staging files, making it an essential tool for reverting changes or simply resetting files to a previous state.

This guide explores the functionality of git restore, providing a detailed overview of how to use it effectively in different scenarios.

Using git restore

Restoring local files to their committed state

To restore a file in the local working directory to its state at the last commit, run:

git restore <file>

For example, to restore a file named example.txt to its last committed state, you would run:

git restore example.txt

Use caution as this command will discard any uncommitted local changes in your file, reverting it to the state it was in at the last commit.

Unstaging files

If you have staged files with the git add command that you later decide not to commit, you can unstage these changes using git restore with the --staged option:

git restore --staged <file>

For instance, if you've staged example.txt and wish to unstage it, you would run:

git restore --staged example.txt

This removes example.txt from the staging area but leaves any changes in your working directory intact.

Restoring and unstaging simultaneously

You can also use git restore to both unstage and restore a file to its last committed state:

git restore --source HEAD --staged --worktree <file>

Here, --source HEAD specifies that the source of the restore should be the last commit (HEAD), --staged applies the restore to the staged changes, and --worktree applies it to the working directory, which discards your local changes. For example:

git restore --source HEAD --staged --worktree example.txt

This command will both unstage and revert example.txt to its state at the last commit.

Restoring from different commits

git restore also allows you to restore files to their state at specific commits. To do this, use the --source option followed by the commit hash or reference:

git restore --source <commit> <file>

For example, to restore example.txt to its state in commit a1b2c3d, you would run:

git restore --source a1b2c3d example.txt

git restore in branch management

Unlike its predecessor git checkout, git restore is mainly used for file restoration within the context of a single branch. It's important to understand its role does not extend to switching branches or managing branch states. For operations involving branches, such as switching between branches, use git switch or git checkout. For more advanced Git workflows, explore our guide on Advanced Git branching strategies for complex projects.

Best practices using git restore

• Use with caution: Since git restore can permanently discard changes (especially uncommitted changes in the working directory), it's good practice to ensure you really want to discard these changes before running the command.
• Commit regularly: Regularly committing your changes can minimize the risk of losing significant work when using commands like git restore, as you can always revert to a previously committed state.

For further reading on the git restore command, see the official Git documentation.

Frequently asked questions

Can I undo a git restore command?

No, git restore permanently discards changes and cannot be undone. If you've already committed your changes, you can use git log to find the commit and restore from there, but uncommitted changes are lost forever.

What's the difference between git restore and git checkout?

git restore is a newer, more focused command specifically for restoring files. git checkout has multiple responsibilities including switching branches and restoring files. For file restoration, git restore is the recommended command since Git 2.23.0. For more Git workflow optimization, check out our guide on Leveling up your Git workflow with Graphite.

Can I restore multiple files at once?

Yes, you can specify multiple files: git restore file1.txt file2.txt file3.txt or use patterns like git restore *.txt to restore all text files.

Does git restore affect committed changes?

No, git restore only affects uncommitted changes in your working directory and staging area. It cannot modify the commit history or affect changes that have already been committed.

What happens if I run git restore on a new file?

If you run git restore on a new file that hasn't been committed yet, the file will be deleted from your working directory since it doesn't exist in the last commit.

Can I restore a file to a specific branch's state?

Yes, you can use git restore --source <branch-name> <file> to restore a file to its state in a different branch without switching to that branch.