git restore Tutorial

The short version

git restore is for restoring file content to a known state. It focuses on paths, not on moving branch pointers.

Why restore exists

Older Git workflows used git checkout -- <path> for many file-recovery tasks. Git later introduced restore so that “switch branches” and “restore file content” would be expressed by different commands.

Two main jobs

Restore the working tree

git restore README.md

This discards unstaged working tree changes and restores the file from the index.

Unstage a file

git restore --staged README.md

This resets the staged version back to HEAD, which makes it a clear way to undo git add.

Restore both index and working tree

git restore --staged --worktree README.md

Use this when you want to unstage and discard the local working copy together.

Restore from a specific commit

git restore --source=HEAD~1 src/app.ts

That lets you recover one path from another commit without moving the entire branch.

restore vs reset

• restore focuses on file state
• reset can affect the index and may also move HEAD

If your real question is “How do I get this file back?”, start with restore.

What problem this command solves in a workflow

git restore is dedicated to recovering file content to a known state. It focuses on paths, not on moving branch pointers. The command can restore the working tree from the index, unstage files back to HEAD, or pull content from any specific commit — making it the clearest tool for "how do I get this file back?" questions.

Typical use cases

• Discard unstaged working tree changes with git restore <path>, reverting the file to match the index.
• Undo git add with git restore --staged <path>, resetting the staged version back to HEAD without touching the working tree.
• Recover a file from a specific commit using git restore --source=<commit> <path>, without moving the entire branch.

Diagram view

Source

Index snapshotHEAD commitAny specified commit (--source)

→git restore

Output

Restored working tree fileUpdated index (with --staged)Both (with both flags)

restore focuses on file state only. It never moves branch pointers or rewrites commit history.

Special cases and boundaries

• git restore <path> discards unstaged changes in the working tree; the overwritten content is not recoverable through Git.
• --staged resets the index to match HEAD, effectively undoing git add without touching working tree files.
• Using both --staged and --worktree together restores the file completely to the source commit's version.
• The --source flag lets you recover content from any commit, tag, or ref, not just HEAD — useful for selective file recovery from history.