Understanding and using the `git restore` command

Greg Foster
Greg Foster
Graphite software engineer

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.

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

Terminal
git restore <file>

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

Terminal
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.

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:

Terminal
git restore --staged <file>

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

Terminal
git restore --staged example.txt

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

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

Terminal
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:

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

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

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:

Terminal
git restore --source <commit> <file>

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

Terminal
git restore --source a1b2c3d example.txt

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.

  • 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.

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2