git restore

Default restore source, --staged versus --worktree, and overwrite risk, checked on Git 2.39.5.

git restore copies file content from a source tree into the working tree, the index, or both. It can discard uncommitted edits. This page documents the default source and the --staged form, and it does not recommend running restore until you have inspected git status and git diff. Git 2.39.5 has no --dry-run option for restore.

Examples were checked on Git 2.39.5 in isolated temporary repositories only. Do not run these restore commands in a repository that holds work you have not reviewed. The discarded working-tree bytes are not saved to a stash or to the reflog.

Examples were checked against Git 2.39.5. See the official documentation for the complete command.

Git command catalog → · Git tutorial overview →

Default source and overwrite risk

Without --staged, git restore writes the working tree. The default source is the index, not HEAD. If you have staged one version and then edited the file again, git restore file replaces the working tree with the staged copy and throws away the later edit.

git restore --source=HEAD -- file takes the file from HEAD instead. In the example that leaves the index still holding the staged copy, so porcelain reports MM: the index differs from HEAD, and the working tree now differs from the index. Always read status before and after a restore.

git restore, git restore --source

git restore [<options>] [--source=<tree-ish>] [--] <pathspec>...
git restore --source=HEAD -- <file>

Replace the working tree copy of a file, by default from the index, which can discard uncommitted edits.

ParameterDescription
<pathspec>The files to restore. Use -- before a path that could look like an option.
--source=<tree-ish>The tree to copy from. When omitted and only the working tree is restored, the source is the index.
--worktree / -WRestore the working tree. This is the default when --staged is not given.

Returns: The selected files in the working tree are overwritten with the source content. There is no stash of the previous working-tree bytes.

  • This is a destructive working-tree operation. Check git diff and git status first. The default source is the index, so restore is not always "go back to the last commit".
  • Git 2.39.5 does not provide git restore --dry-run.
bash
git init -b main >/dev/null
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
printf 'head\n' > f.txt
git add f.txt
git commit -m "HEAD content" >/dev/null
printf 'staged\n' > f.txt
git add f.txt
printf 'worktree\n' > f.txt
echo "before $(cat f.txt)"
git status --porcelain=v1
git restore f.txt
echo "default $(cat f.txt)"
git status --porcelain=v1
printf 'worktree\n' > f.txt
git restore --source=HEAD -- f.txt
echo "source-HEAD $(cat f.txt)"
git status --porcelain=v1

Expected output

before worktree
MM f.txt
default staged
M  f.txt
source-HEAD head
MM f.txt

Related: git status, git stash

Official documentation →

Unstaging and restoring both sides

git restore --staged copies from HEAD into the index by default, which unstages a file and leaves the working tree alone. In the example the worktree still contains the last edit, and porcelain is " M".

git restore --staged --worktree copies HEAD into both the index and the working tree. That discards staged and unstaged edits for the path. The example ends clean. Use it only when you intend to throw those edits away.

git restore --staged, git restore --staged --worktree

git restore --staged [--] <pathspec>...
git restore --staged --worktree [--] <pathspec>...

Unstage a file without touching the working tree, or reset both the index and the working tree to HEAD.

ParameterDescription
--staged / -SRestore the index. The default source is then HEAD.
--worktree / -WAlso restore the working tree when combined with --staged. Together, both sides come from HEAD unless --source is set.

Returns: The index, and optionally the working tree, match the source tree for the given paths.

  • --staged alone is usually safe for the working tree, because it does not overwrite file contents. Adding --worktree is the overwrite.
bash
git init -b main >/dev/null
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
printf 'head\n' > f.txt
git add f.txt
git commit -m "HEAD content" >/dev/null
printf 'staged\n' > f.txt
git add f.txt
printf 'worktree\n' > f.txt
git restore --staged -- f.txt
echo "unstaged $(cat f.txt)"
git status --porcelain=v1
printf 'staged\n' > f.txt
git add f.txt
printf 'worktree\n' > f.txt
git restore --staged --worktree -- f.txt
echo "both $(cat f.txt)"
st=$(git status --porcelain=v1)
if [ -z "$st" ]; then echo "(clean)"; else printf "%s\n" "$st"; fi

Expected output

unstaged worktree
 M f.txt
both head
(clean)

Official documentation →