Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 78 ยท Rewriting History

git reset in Depth

Understand git reset through the three trees: what --soft, --mixed and --hard move, how reset differs from checkout and restore, resetting paths, ORIG_HEAD and hard reset dangers.

git reset has a reputation for being scary, and it deserves some of it: one of its modes throws away work. But the command is simple once you see what it actually does. It moves a branch pointer, and then, depending on a flag, it also changes the staging area and your files to match.

Undoing Things gave you the quick overview. This lesson builds the full mental model on top of How Git Works: three places where your project lives, and three modes that decide how far a reset reaches into them. After that, reset stops being a spell you copy from a forum answer and becomes a tool you can predict.

The three trees

Git keeps three versions of your project at the same time:

Name Where it lives What it holds
HEAD the commit your current branch points to the last commit: the snapshot you started from
Index .git/index the staging area: your proposal for the next commit
Working tree your folder the real files you edit
TEXT
   HEAD (last commit)     Index (staged)      Working tree (files)
   ------------------     --------------      --------------------
          |                     ^                     ^
          |    git add          |                     |
          |  <----------------- |  <----------------- |   (you edit, then add)
          |                     |                     |
          |    git commit       |                     |
          | ------------------> |                     |

git reset works from the left. It always takes the target commit you name (default HEAD) and walks through up to three steps:

  1. Move the branch that HEAD points to (not HEAD itself) to the target commit.
  2. Index: make the index look like that commit.
  3. Working tree: make the files look like that commit.

The three modes are just "how many steps do we do?":

Mode Step 1: move branch Step 2: reset index Step 3: reset files
--soft yes no no
--mixed (default) yes yes no
--hard yes yes yes

Let us watch each one. All the examples below use the same little history, built by a helper function so that hashes are stable.

Reset --soft: move the branch, keep everything staged

--soft only does step 1. The branch moves back, but the index and your files still contain the changes from the commits you "removed". Everything looks as if you had staged those changes and not yet committed them.

Bash reset --soft: undo the commit, keep it staged

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The log lost its newest commit, but git status -s shows A c.txt: the file is still staged, and it is still on disk. Nothing was lost. This is the perfect tool for "I committed too early, let me redo the commit": reset softly, then git commit again with a better message or after adding more files. Resetting several commits softly (HEAD~3) and committing once is the quickest way to squash them.

Reset --mixed: unstage, keep the files

--mixed is the default when you give no flag. It does steps 1 and 2: the branch moves and the index is reset, but your files stay as they are. The changes are still there, only no longer staged.

Bash reset --mixed: undo the commit and the staging

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The status line is ?? c.txt: since the commit that tracked the file is gone and the index no longer holds it, Git sees an untracked file. A second, very common use of --mixed is unstaging: git reset with no commit and no path clears the whole index, and git reset -- file unstages one file (more below).

Reset --hard: move everything, discard the changes

--hard does all three steps. The branch moves, the index follows, and your files are overwritten to match the target commit. Any uncommitted changes to tracked files are gone, and there is no undo for them because Git never stored them.

Bash reset --hard: files change on disk

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

b.txt vanished from the folder because it did not exist in the target commit, and the uncommitted line in a.txt is gone with no trace. git reset --hard with no target (git reset --hard, same as HEAD) is the standard way to say "throw away all my uncommitted work and make everything match the last commit".

--hard destroys uncommitted work for good. Committed work is different: the commits you moved away from still exist in the reflog for a while and can be recovered. A change you never committed (or at least staged with git add) has no copy anywhere. Run git status and git diff before any reset --hard.

ORIG_HEAD: the safety rope

Before a risky operation (reset, merge, rebase, pull) Git saves where HEAD used to be in a ref called ORIG_HEAD. That makes the most common regret trivial to fix: you reset too far, so you reset back to where you came from.

Bash Undo a reset with ORIG_HEAD

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The hash printed before the reset and the hash after reset --hard ORIG_HEAD are the same: we are back. ORIG_HEAD is overwritten by the next risky command, so use it immediately. For anything older, use git reflog (see The Reflog and Recovering Lost Work). Remember that this only helps for committed work: if your --hard reset discarded uncommitted edits, ORIG_HEAD cannot bring them back.

Reset with paths: no branch movement

When you give git reset a path, the rules change. A branch cannot move "for one file", so step 1 is skipped. Path reset only copies the file from a commit (default HEAD) into the index. That is why it unstages.

TEXT
git reset -- notes.txt           # index gets HEAD's notes.txt = "unstage notes.txt"
git reset abc1234 -- notes.txt   # index gets the version from abc1234

Modes make no sense with paths: git reset --hard -- file is an error, because it would have to move a branch. If you want the file from another commit in your working tree too, you want git restore, covered below.

Bash Reset a path: unstage without losing the edit (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

After the path reset, a.txt shows M (modified, not staged) and b.txt stays M (staged). The edit itself survived. The last command fails with fatal: Cannot do hard reset with paths.

Reset, checkout and restore compared

Three commands overlap, which confuses everyone. Here is the difference in terms of the trees:

Command Moves the branch? Changes the index? Changes the files? Safe for your uncommitted work?
git reset --soft <c> yes no no yes
git reset [--mixed] <c> yes yes no yes
git reset --hard <c> yes yes yes no
git reset <c> -- file no yes (that file) no yes
git restore --staged file no yes (that file) no yes
git restore file no no yes (that file) no
git restore -s <c> file no no yes (that file) no
git checkout <branch> moves HEAD, not the branch yes yes refuses if it would overwrite changes

Two differences are worth remembering:

  • reset moves the current branch; checkout/switch move HEAD to another branch. After git checkout other, the branch you left stays where it was. After git reset other, the branch you are on has been dragged to where other points.
  • reset --hard does not ask; checkout and switch refuse to overwrite local changes. git checkout -- file and git restore file do overwrite, like --hard but for one file.
Bash reset moves the branch, switch does not

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

switch left main untouched; reset --hard old pulled main back to the commit where old points, and the two commits that were only on main are now unreachable (but recoverable through the reflog for a while).

Practical recipes

Undo the last commit, keep the changes staged: git reset --soft HEAD~1.

Undo the last commit and unstage, keep the changes in files: git reset HEAD~1.

Squash the last three commits into one: git reset --soft HEAD~3, then git commit -m "One message". For something more selective, use interactive rebase.

Throw away everything not committed: git reset --hard (plus git clean for untracked files).

Make your local branch match the remote exactly (after a fetch): git reset --hard origin/main. This discards your local commits on that branch, so check git log origin/main..main first to see what you would lose. See Remotes.

Split a commit into two: git reset HEAD~1, then add and commit the pieces separately (see Amending, Splitting and Rewriting Commits).

Bash Squash three commits with reset --soft

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Resetting published history

Reset rewrites your branch. If those commits were already pushed and others have built on them, resetting and pushing again forces everyone else to clean up. For shared branches use git revert, which adds a new commit that undoes an old one instead of erasing it. The same golden rule appears in Rebasing.

Before a --hard reset, make a bookmark: git branch backup costs nothing and keeps every commit reachable. Delete it later with git branch -D backup once you are sure.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which steps does git reset --mixed (the default) perform?

    --soft moves only the branch, --mixed also resets the index, and --hard also overwrites the working tree.
  2. 2. You committed too early and want to redo the commit with the same changes still staged. Which command?

    --soft HEAD~1 moves the branch back one commit and leaves the index and files untouched, so the changes are still staged.
  3. 3. What does git reset -- notes.txt do?

    With a path, reset skips moving the branch and only copies the file from the commit into the index. The file on disk keeps its edits.
  4. 4. You ran git reset --hard HEAD~3 and want the three commits back right away. What is the quickest way?

    Git stores the previous position of HEAD in ORIG_HEAD before a reset, so resetting to it undoes the move. The reflog also works for older positions.
  5. 5. Which uncommitted work can git reset --hard bring back?

    Unstaged edits are never stored by Git, so a hard reset removes them for good. Committed work can be recovered from the reflog.

Summary

  • Git has three trees: HEAD (last commit), the index (staging area) and the working tree. Reset moves the branch, then optionally updates the other two.
  • --soft moves the branch only, --mixed (default) also resets the index, --hard also overwrites your files and is the only dangerous mode.
  • Reset with a path never moves the branch: it copies the file into the index, which is how you unstage.
  • ORIG_HEAD remembers where HEAD was before a reset, merge or rebase, so git reset --hard ORIG_HEAD undoes it.
  • reset drags the current branch; switch/checkout move HEAD to another branch; restore changes files or the index without moving anything.
  • Do not reset published history: use git revert there.

Next: Rebasing