Git Restore: Correcting Working Tree and Index State

Basic

What git restore changes

`git restore` restores selected paths from a restore source into a selected location. It can change the working tree, the index, or both. It does not create a new commit and does not move a branch name or rewrite existing commits. This lesson treats restore as a state-correction operation, not as a history-rewriting operation.

git restore path/to/file
git restore --staged path/to/file
git restore --source=HEAD --staged --worktree path/to/file

A tracked path needs local state correction.?Git restores selected path content; no commit is created.

Default restore: index to working tree

With neither `--staged` nor `--worktree` specified, `git restore` restores the working tree from the index. This is useful when the working copy contains changes that should be discarded in favor of the currently staged version. Because this can destroy uncommitted working-tree content, inspect the diff first when the content matters.

git diff -- path/to/file
git restore -- path/to/file
git diff -- path/to/file

HEAD and index contain the staged version; the working tree contains an additional edit.?The working tree is made to match the index for that path.

Restore the index from HEAD

`git restore --staged file` changes the index so that the selected path matches `HEAD`. The working tree is not changed by this form. This is a precise way to remove a path's staged change while preserving a separate working-tree edit.

git add file.txt
git restore --staged file.txt
git diff --cached -- file.txt

The index contains a staged change while the working tree still has that content.?The index matches HEAD again; the working tree remains available for further editing.

Choose a different source

`--source=<tree>` changes where restore obtains content. The source can be a commit, branch, or tag that names a tree. For example, restoring a path from `HEAD~1` changes the selected destination to the version represented by that earlier commit; it does not move `HEAD` back to that commit.

git restore --source=HEAD~1 -- path/to/file
git diff -- path/to/file

HEAD still identifies the current commit.?The selected path can receive content from HEAD~1 while HEAD remains unchanged.

Restore both index and working tree

Specifying both `--staged` and `--worktree` restores both locations. When both are specified, Git requires an explicit `--source`, because the command must know which tree should supply both destinations. A common explicit form is `git restore --source=HEAD --staged --worktree file.txt`.

git restore --source=HEAD --staged --worktree file.txt
git status --short

The selected path differs in one or both local locations.?Both locations are restored from the selected source tree.

Deletion and recovery of a tracked path

If a tracked file is deleted from the working tree, `git restore file.txt` can restore it from the index. If the index has also been changed and the desired version is the committed one, `git restore --source=HEAD --staged --worktree file.txt` restores both locations from `HEAD`. These are state operations; neither creates a new history entry.

rm file.txt
git restore -- file.txt
git status --short

file.txt is absent from the working tree but remains represented in the index.?The tracked working-tree path is recreated from the index.

Restore is not reset or revert

The commands overlap in some effects but own different concepts. `git restore` changes selected working-tree and/or index content. `git reset` will be taught separately as a broader reference/index/history-state operation. `git revert` creates a new commit that reverses an earlier commit. Do not use `git restore` as a synonym for undoing history.

git restore -- path/to/file
# no commit is created
# HEAD and branch references stay where they were

HEAD identifies the same commit before and after a restore operation.?Only the selected local state is corrected.

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official-source boundary

This lesson is based on the official Git documentation for `git restore` and the official Git revision syntax used for restore sources. It intentionally postpones the broader reset/revert comparison until those commands have their own curriculum ownership.