git restore

Definition

The git restore command restores files in your working tree or staging area to a known-good version. Introduced in Git 2.23 alongside git switch, it took over the file-restoring duties that used to be buried inside git checkout. Its job is to answer one question: where should the clean copy of this file come from?

Discarding working-tree changes

By default, git restore overwrites a file in your working directory with the version from the staging area (the index). If you have edited a file and want to throw those edits away:

git restore index.html

The file returns to its last staged state. Because this is destructive — unstaged edits are gone — Git deliberately gives the operation a clear name rather than hiding it behind checkout.

Unstaging with --staged

To remove a file from the staging area without changing its contents, use --staged. This copies the version from HEAD back into the index, leaving your working-tree edits intact:

git restore --staged index.html

This is the modern replacement for git reset HEAD <file>. It is exactly what Git suggests when you run git status after staging something.

Restoring from a specific commit

The --source option lets you pull a file's contents from any commit, branch, or tag — not just the index or HEAD:

git restore --source=HEAD~2 config.yml

This rewinds a single file to how it looked two commits ago, without touching anything else.

Common options

restore vs reset vs revert

These three commands are easy to confuse:

• git restore operates on files in the working tree and index. It never moves branch pointers or rewrites history.
• git reset moves the current branch tip and can change the staging area — it operates at the commit level.
• git revert creates a new commit that undoes a previous one, leaving history intact.

Reach for restore when you simply want a file to look the way it did somewhere else.

Practice