Git Restore: Unstage Files & Discard Changes (Complete Guide for 2026)

Published February 16, 2026 · 12 min read

git restore is the safest way to undo local file changes in modern Git. It can do two extremely common tasks:

• Discard edits in your working directory (undo a local change)
• Unstage files (undo git add) without rewriting history

It was introduced (along with git switch) to split the overloaded behavior of git checkout into clearer commands. If you still reach for checkout every time you want to undo a file, this guide is for you.

1. Copy/paste recipes (the 90% cases)

Unstage a file (keep changes)

# Undo: git add file.txt
# Keeps your working tree edits
git restore --staged file.txt

Discard local changes to a file (danger: deletes edits)

# Restore file.txt to the last committed version
git restore file.txt

Restore a file from another commit (or another branch)

# Bring file.txt back from a specific commit
git restore --source <commit> -- file.txt

# Bring file.txt from another branch without switching
git restore --source origin/main -- file.txt

2. What git restore actually changes (worktree vs index)

To use git restore confidently, you need one mental model: Git has three places your content can live:

• HEAD: the last committed snapshot (your current commit)
• Index / staging area: what will go into the next commit
• Working tree: the files on disk you are currently editing

git restore changes file contents in the working tree, the index, or both — but it does not move HEAD. That makes it ideal for file-level undo operations.

3. Discard local changes (working tree)

If you edited a file and want to throw away those edits:

# Discard changes in working tree
git restore file.txt

You can restore multiple paths at once:

# Restore two files
git restore file1.txt file2.txt

# Restore everything under a directory
git restore src/

4. Unstage files (undo git add)

Unstaging is one of the best uses of git restore because it’s precise and doesn’t change history:

# Undo: git add file.txt
git restore --staged file.txt

Unstage everything:

# Unstage everything (keeps edits)
git restore --staged .

5. Restore from another commit or branch

Sometimes you don’t want the version from HEAD — you want the version from a specific commit or a different branch. That’s what --source is for.

# Restore a file exactly as it was in a specific commit
git restore --source <commit> -- path/to/file

# Restore a file from another branch
git restore --source origin/main -- path/to/file

The -- is optional in many cases, but it is a good habit when file paths could be confused with branch names.

6. Interactive restore with --patch

--patch lets you choose hunks interactively (very useful when you made multiple unrelated edits).

Discard only some hunks from the working tree

git restore --patch file.txt

Unstage only some hunks

git restore --staged --patch file.txt

7. Restore vs reset vs checkout (when to use what)

These commands overlap, which is why Git can be confusing. Here’s the simplest decision rule:

• Undo commits: use git revert (pushed) or git reset (local)
• Undo files: use git restore
• Switch branches: use git switch (or checkout)

8. Troubleshooting

“pathspec did not match any file(s) known to git”

The path you typed doesn’t exist in the index/HEAD at the moment (typo, wrong directory, or the file is untracked). Check:

git status
ls

How do I restore an untracked file?

git restore restores tracked paths. For untracked files, Git doesn’t have a snapshot to restore. If you truly want to delete untracked files, use git clean (careful):

# Preview first
git clean -n

# Then delete
git clean -f

I restored a file but it’s still “modified”

This often means you have staged changes that differ from HEAD. Check both diffs:

# Unstaged diff (working tree vs index)
git diff

# Staged diff (index vs HEAD)
git diff --staged

FAQ

Is git restore safe on shared branches?

Yes. git restore is a local working-tree/index operation and doesn’t rewrite commit history. The “shared branch danger zone” is mostly about commands that rewrite history (git reset + force push, rebases on shared branches, etc.).

How do I undo an accidental merge or pushed commit?

That’s a commit-history problem, not a file problem. See: Git Revert a Merge Commit and Git Undo: Reset, Revert & Restore.

What replaced “git checkout -- file.txt”?

Use git restore file.txt to restore the file in your working tree, or git restore --staged file.txt to unstage.

If you want a broader decision guide (including reset vs revert vs restore and recovery with reflog), see: Git Undo: Reset, Revert & Restore.