System Atlas
the atlas

How git reset works

One command, three trees, and the difference between undo and disaster.

the gist

git reset moves your branch pointer to a chosen commit and then, depending on the flag, optionally rewrites the staging area and working directory. --soft moves only HEAD, --mixed (the default) also resets the index, and --hard also overwrites your files — which is the one that destroys work. When history is shared, prefer git revert, which undoes changes with a new commit instead of rewriting the past.

ANALOGY // It's like rewinding a document to an earlier autosave: --soft keeps your clipboard and unsaved edits, --mixed empties the clipboard but keeps the edits, and --hard rewinds the file itself and throws today's typing away.
living diagram01 / 06
git resettarget <ref>Target commitwhere HEAD landsHEADbranch pointerIndexstaging areaWorking diryour filesgit revertnew inverse commit
01

The three trees

Git tracks your work in three places at once: HEAD points at your last commit, the index (staging area) holds the snapshot you're about to commit, and the working directory holds the actual files you edit. Almost every git command is really just moving data between these three trees. Understanding reset means understanding which of the three each flag touches.

02

--soft moves HEAD only

With --soft, git moves the branch pointer to the target commit and stops there — the index and working directory are left exactly as they were. The net effect is that everything from the commits you rewound past is now sitting neatly staged, ready to be recommitted. This is the tool for squashing several commits into one or rewriting a commit message without losing any content.

03

--mixed resets the index (default)

--mixed is what you get when you run git reset with no flag. It moves HEAD to the target and also resets the index to match, but leaves your files untouched. The changes you rewound past therefore appear as unstaged modifications in your working directory — nothing is lost, it's just no longer staged. This is the natural way to unstage files or redo how you group changes.

04

--hard resets everything

--hard moves HEAD, resets the index, and overwrites the working directory to match the target commit. That third step is the dangerous one: any uncommitted changes in your files are discarded with no confirmation. It's the fastest way to throw away a messy experiment and return to a known-good state, but running it on work you haven't committed is how people lose an afternoon.

05

reset vs revert

reset rewinds the branch by moving its pointer, which rewrites history — fine on your own local branch, but a problem if you've already pushed and others have pulled. git revert instead creates a brand-new commit that is the inverse of a previous one, undoing its effect while leaving history intact. On any shared branch, revert is the correct, collaboration-safe way to undo.

06

Choosing the right tool

Reach for --soft to reshape recent local commits, --mixed to re-stage or unstage work, and --hard only when you're certain the uncommitted changes are disposable. Prefer revert whenever the commit has been shared. And remember the reflog: even a --hard usually leaves the old commit recoverable for a couple of weeks, so a mistake is rarely truly fatal.

the full picture
01

The problem reset solves

Every developer eventually commits too early, stages the wrong file, or wants to collapse a flurry of wip commits into one clean change. git reset is the command for rewinding your branch to a chosen point in its history and deciding, precisely, how much of your current work to bring back with you.

The reason reset confuses people is that it does not do just one thing — it does up to three things, and a single flag controls how far it reaches. To use it confidently you first have to understand the model of state that git maintains underneath, because reset is really just a controlled way of shuffling data between the parts of that model.

02

The three trees

Git juggles three snapshots of your project at all times, and the documentation calls them the "three trees":

  • HEAD — a pointer to your most recent commit on the current branch. It represents "the last thing I saved to history."
  • The index (also called the staging area or cache) — the snapshot you are building up to become your *next* commit. git add copies changes from your files into here.
  • The working directory — the actual files on disk that you edit in your editor.

A normal commit takes the index, freezes it into a new commit, and advances HEAD to point at it. git reset runs that machinery in reverse: it moves HEAD to an older commit and then, depending on the flag, optionally rewrites the index and the working directory to match. Knowing which of the three trees a given flag touches is the entire secret to the command.

03

The three modes

reset always moves HEAD. The flag decides how far the reset cascades from there.

  • git reset --soft <ref> moves only HEAD. The index and working directory are untouched, so every change from the commits you rewound past is left neatly staged, ready to recommit. This is the classic way to squash the last few commits into one or to rewrite a commit message: reset softly to the commit before them, then commit again.
  • git reset --mixed <ref> is the default (running git reset with no flag does this). It moves HEAD and resets the index to match, but leaves your files alone. Your changes survive as *unstaged* modifications. This is how you unstage a file you added by mistake (git reset HEAD file) or reorganize how work is grouped before committing.
  • git reset --hard <ref> moves HEAD, resets the index, and overwrites the working directory to match the target. This is the only mode that touches your files, and it does so without asking — any uncommitted change is discarded. It is perfect for abandoning a broken experiment and snapping back to a clean state, and dangerous for exactly the same reason.

A useful way to remember it: --soft keeps changes staged, --mixed keeps them unstaged, and --hard keeps nothing.

04

reset vs revert — rewriting vs recording

reset rewinds a branch by *moving its pointer*, which means it rewrites history — the commits you moved past are no longer on the branch. On a private, local branch that is completely fine and often exactly what you want. But if you have already pushed those commits and teammates have pulled them, rewriting the branch makes your history diverge from theirs, and the next push either fails or, if force-pushed, silently clobbers their work.

git revert exists for that situation. Instead of erasing a commit, it creates a new commit whose diff is the exact inverse of the target, cancelling out its effect while leaving every existing commit in place. History only grows, never changes, so everyone's clones stay compatible. The rule of thumb is simple: use reset to tidy up work that lives only on your machine, and use revert to undo anything that has already been shared.

05

Safety, recovery, and practical guidance

The scary reputation of reset --hard is only half-deserved, because git rarely deletes commits immediately. When you move HEAD, the commit you left behind becomes "unreferenced," but it lingers in the repository and — crucially — in the reflog, a local log of everywhere HEAD has pointed. Running git reflog shows those recent positions, and you can recover a seemingly lost commit with git reset --hard <old-sha> or by branching from it. Unreferenced commits are only truly removed later, when garbage collection runs (typically after a couple of weeks).

The one thing the reflog cannot save is work that was never committed at all: a --hard throws away uncommitted edits in your working directory, and those leave no trace. So the practical discipline is to commit or git stash anything you might want before a hard reset, prefer --soft/--mixed when you only need to reshape commits, and reach for revert the moment history has left your laptop. Treat reset as a scalpel with three depth settings — powerful and precise once you know which tree each one cuts into.

what to remember
01

Git has three trees: HEAD (last commit), the index (staging area), and the working directory (your files).

02

reset --soft moves only HEAD — your staged changes and edits are kept, ready to recommit.

03

reset --mixed (the default) moves HEAD and resets the index, so changes become unstaged but survive in your files.

04

reset --hard moves HEAD and overwrites the index AND working directory — uncommitted work is gone.

05

reset rewrites history; revert adds a new inverse commit and is the safe choice on shared branches.

06

Even after a --hard, the old commit usually survives in the reflog for a while, so recovery is often possible.

check yourself

Quick quiz

Q1

Which reset flag can destroy uncommitted work in your files?

Q2

You've already pushed a commit others have pulled. How should you undo it?

follow the thread