Introduction

Undoing local changes to one file in Git depends on where those changes live. A file may be modified only in the working tree, staged in the index, or already committed locally. Each case uses a different command, so the first step is understanding the file’s current state.

Check the File State First

Start with:

git status -- path/to/file

This tells you whether the file is:

• modified but unstaged
• staged for commit
• both staged and further modified

Once you know that, choose the right restore command.

Undo Unstaged Changes

If the file is modified in the working tree but not staged, restore it from HEAD:

git restore path/to/file

That discards your local edits and makes the file match the current commit.

Older examples often use:

git checkout -- path/to/file

That still appears in older material, but git restore is the clearer modern command for this task.

Unstage a File Without Losing the Edits

If the file is staged and you only want to remove it from the index, use:

git restore --staged path/to/file

This keeps your working-tree edits but removes the file from the next commit.

That is useful when you ran git add too broadly and want to keep editing before staging again.

Discard Both Staged and Unstaged Changes

If the file is staged and you also want to throw away the actual content changes, do it in two steps:

git restore --staged path/to/file
git restore path/to/file

After those commands, the file matches HEAD again and no local edits remain.

Restore a File From a Different Commit

Sometimes “undo” means “replace the current file with the version from another commit.” In that case, specify a source revision:

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

That writes the file from the previous commit into your working tree. You can inspect it, stage it, and commit it if that is the version you want to keep.

This is safer than rewriting branch history when all you really need is one earlier version of one file.

When a Local Commit Already Exists

If you already committed locally and have not pushed yet, there are two general choices:

1. create a new commit that restores the file
2. rewrite local history

For a single-file correction, the first option is usually simpler and less risky:

git restore --source=HEAD~1 -- path/to/file
git add path/to/file
git commit -m "Restore path/to/file"

That keeps history explicit and avoids rewriting other local work.

Use Diff Before You Discard Work

Before running restore commands, inspect what you are about to lose:

git diff -- path/to/file

If the file is staged:

git diff --cached -- path/to/file

That small habit prevents a lot of accidental data loss.

Common Pitfalls

The biggest mistake is running git restore path/to/file without realizing it permanently discards unstaged edits in that file.

Another issue is confusing unstaging with restoring. git restore --staged changes the index, not the file contents in your working tree.

Developers also reach for git reset --hard when they only need to fix one file. That is much broader and can destroy unrelated work.

Finally, if the file includes user changes you might want later, stash or copy it before discarding anything.

Summary

• Use git restore path/to/file to discard unstaged changes in one file.
• Use git restore --staged path/to/file to unstage it while keeping the edits.
• Use both commands if you want to remove the file from staging and discard the edits.
• Use git restore --source=<commit> when you want the file from another revision.
• Check git diff first so you know exactly what will be lost.