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.
Best practices using git restore
- Use with caution: Since
git restorecan 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.
