git-restore

Restore an unstaged file to the staged version

$ git restore [path/to/file]

$ git restore [[-s|--source]] [commit] [path/to/file]

$ git restore :/

$ git restore [[-S|--staged]] [path/to/file]

$ git restore [[-S|--staged]] :/

$ git restore [[-W|--worktree]] [[-S|--staged]] :/

$ git restore [[-p|--patch]]

git restore [] [--source=] [--staged] [--worktree] [--pathspec-from-file= [--pathspec-file-nul]] [--] ...

--source=
    Restore files from the specified <tree> (e.g., commit hash, branch name, tag name). If not specified, HEAD is used for --staged and the index is used for --worktree.

-s, --staged
    Restore files into the index. This effectively unstages changes, reverting the index to match the HEAD commit or the specified --source.

-W, --worktree
    Restore files into the working tree. This is the default action if neither --staged nor --worktree is specified, or if --staged is not specified. It discards working tree changes, reverting files to match the index or the specified --source.

--pathspec-from-file=
    Read pathspecs from <file> instead of from the command line. Pathspecs are usually one per line.

--pathspec-file-nul
    Only meaningful with --pathspec-from-file. Pathspecs in the file are separated by NUL characters instead of newlines.

-p, --patch
    Interactively select hunks of changes to restore. This allows reviewing and selecting specific parts of changes to be reverted.

--dry-run
    Don't actually restore anything, just show what would be done.

-q, --quiet
    Suppress all output.

-v, --verbose
    Be verbose.

...
    Optional path(s) to restore. If omitted, the entire working tree and/or index (depending on flags) is affected.

The git restore command is used to restore specified paths in the working tree or the index from a given source. Introduced in Git 2.23, it aims to clarify the functionality previously overloaded by git checkout.

While git checkout could switch branches, restore files, and restore files from a specific commit, git restore focuses solely on file restoration. This separation of concerns (git switch for branch switching, git restore for file restoration) makes Git's command line interface more intuitive and less prone to user error.

It can be used to discard uncommitted changes in the working directory, unstage changes from the index, or revert a file to an earlier state from any commit in the repository history.

git restore only operates on file paths; it does not switch branches or update HEAD. For branch switching, use git switch. It can restore files from the index (to working tree) or from HEAD (to index), or from any specified commit. Be aware that restoring changes will overwrite local modifications unless --patch is used.

When no --source is explicitly provided:
1. git restore <pathspec>... (without --staged): Restores the working tree files to match the state of the index.
2. git restore --staged <pathspec>...: Restores the index to match the state of the HEAD commit.
3. git restore --staged --worktree <pathspec>...: Restores both the index and the working tree to match the state of the HEAD commit.

To restore a file or set of files to their state at a particular commit, use the --source option:
git restore --source=<commit-hash> <file>
This command will take the version of <file> from <commit-hash> and place it into your working tree. If you also want to stage it, add --staged.

The git restore command was introduced in Git version 2.23 (released August 2019). Its primary motivation was to address the overloaded nature of the git checkout command. Historically, git checkout performed three distinct operations: switching branches, restoring working tree files, and restoring files from a specific commit. This multi-functionality often led to confusion. To improve clarity and user experience, the Git project decided to split these responsibilities. git switch was introduced for branch operations, and git restore for file restoration, allowing git checkout to remain for backward compatibility but encouraging users to adopt the more explicit new commands.

git-switch(1), git-checkout(1), git-reset(1), git-add(1), git-rm(1)