The undo map

Why this matters

Almost every Git mistake is one of six situations, and each has one right answer. This page is the map; the lessons after it are the detail. If you read only one page in this section, read this one.

The map

The question that decides everything

Before choosing, ask: has this been pushed where other people can see it?

That single question resolves most of the confusion between reset and revert, which is the pair people mix up most.

The six situations

1. I changed a file and want the committed version back

$ git status --short

 M docs/faq.md

$ git restore docs/faq.md

Nothing is printed, and git status is clean again. The edit is gone for good: Git never recorded it, so the reflog cannot help. This is the most genuinely destructive command in everyday use, which is why it is worth pausing on.

2. I staged something by mistake

$ git add docs/getting-started.md
$ git status --short

M  docs/getting-started.md

$ git restore --staged docs/getting-started.md
$ git status --short

 M docs/getting-started.md

The M moved from the left column to the right: staged, then merely modified. Your edit is kept; only the staging is undone. Note how similar the two commands are, and how different the consequences: --staged is the safe one.

3. My last commit needs fixing, and I have not pushed it

$ git commit -am "docs: add Windos section"
$ git log --oneline -1

2c4263b docs: add Windos section

$ git commit --amend -m "docs: add Windows section"
$ git log --oneline -1

97fc096 docs: add Windows section

The hash changed, which is the sign that this rewrites history: the old commit is replaced rather than edited. Fine while it is yours alone, a problem the moment it is pushed. git commit --amend --no-edit also works for "I forgot a file": stage the file, then amend.

4. A commit is wrong and it is already pushed

$ git revert 97fc096

[main 4bd6eb3] Revert "docs: add Windows section"
 1 file changed, 2 deletions(-)

$ git log --oneline -3

4bd6eb3 Revert "docs: add Windows section"
97fc096 docs: add Windows section
d3b92ec chore: add CI configuration and contributing guide

Both commits are in the history: the mistake and its undo. That is the point. Everyone else's clone still matches yours, and nobody has to do anything. This is the only safe undo for shared work.

5. I want to move my branch back, and I have not pushed

$ git reset --soft HEAD~1
$ git status --short

A  .github/workflows/ci.yml
A  .gitlab-ci.yml
A  .markdownlint.json
A  CONTRIBUTING.md

The commit is gone from the branch and its changes are staged, ready to be re-committed differently. That is --soft; --mixed and --hard differ in where the changes land, which is lesson 12.4 and worth reading before using --hard.

6. I need to park unfinished work

$ git stash push -m "windows draft"

Saved working directory and index state On main: windows draft

$ git stash list

stash@{0}: On main: windows draft

$ git stash pop

 M docs/getting-started.md
?? notes.txt

The tree is clean while the work waits, and pop brings it back. Note that plain git stash leaves untracked files where they are; git stash -u includes them.

The pairs people confuse

How to do it

Common mistakes

• Reaching for reset on pushed work. Use revert; the pushed commit is already in other people's clones.
• Typing git restore <file> when you meant --staged. One discards your work, the other does not.
• Amending a pushed commit, which forces everyone else to reconcile a history that no longer matches.
• Using git stash as storage. It is a pocket, not a drawer; stashes accumulate and get forgotten (command page).
• Running the fix before reading git status, which usually tells you which situation you are in.