The previous lesson set up the catalogue and solved the one-minute cases. Now it is the turn of the command that appeared in half a dozen rows of that table and that we have been promising for five modules: git reset.

It is probably the worst understood command in Git. It has three modes that do different things, two ways of invoking it that behave in completely different ways, and a reputation for being dangerous that is only deserved in one of its uses. The confusion is not accidental: reset does two jobs that in other systems would be two separate commands.

This lesson takes it apart piece by piece and then puts it in context. Because reset is not the answer to "I want to undo something": it is one of the answers, and choosing the wrong one is what turns an unwanted change into a problem for the whole team. By the end you will have a decision table that answers the only question that matters: where is the thing I want to undo?

And a warning that holds for the whole lesson: this is where the one Git command that truly destroys, with no possible safety net, makes its appearance. It is not reset. It is git clean.

1. The three areas, once again
2. git reset moves the branch: the central idea
3. The three modes: --soft, --mixed, --hard
4. Cases arranged by what you want to undo
5. git reset <commit> -- <path>: the other form
6. git restore: the modern command for everyday work
7. git clean: the one that really does destroy
8. ORIG_HEAD: the immediate safety net
9. The decision table

Every reset becomes clear as soon as you recall the three areas from lesson 01-03. It is worth having them in front of you:

Three snapshots of the project that may or may not agree:

When git status says "Changes to be committed", it is comparing the index with HEAD. When it says "Changes not staged for commit", it compares the working directory with the index. With that clear, reset stops being a mystery: each mode decides how far through those three areas the change reaches.

Before the modes, the basic operation. This is what git reset <commit> does always, in all three modes:

It moves the current branch so that it points at <commit>. And since HEAD points at the branch, HEAD moves along with it.

It does not delete commits. It does not modify commits. It rewrites a 41-byte file (lesson 03-01).

b52c9d1 and 7d3a8f4 still exist in full in .git/objects. What has changed is that GT-241 no longer reaches them, so git log does not show them. Recovering them is trivial as long as the reflog remembers them (lesson 09-04).

From this come the two consequences you need to internalise:

1. reset is safe on local work. Even if you get it wrong, the commits are still there.

2. reset is dangerous on published work. Because moving the branch backwards and then forwards again produces a different history from the one others have. The push will be rejected (non-fast-forward), and forcing it would destroy other people's work. It is the golden rule from lesson 05-01, and its full treatment is lesson 09-03.

A third nuance that hardly anyone knows about and that avoids a lot of scares:

With no commit argument, reset uses HEAD, which is to say it moves nothing. It only acts on the index. That is why a bare git reset is completely harmless: it empties the staging area and leaves your files intact.

The difference between the three is how far it propagates the change.

Visually, over the three areas:

The commit has disappeared from the branch, and all its content is staged, ready to be committed again. The M and A with the letter in the first column mean "in the index".

It is the "I want to redo this commit" mode. In fact, it is exactly what git commit --amend does under the bonnet.

Now the letter is in the second column: the changes are in the working directory, unstaged. And styles.css, which was new, has gone back to being an untracked file.

It is the "I want to redo this commit and choose again what goes in" mode. It is the one you used in lesson 05-02 to split a commit in two.

Everything clean, as if that commit had never existed. And here lies the danger, which is worth stating precisely:

--hard does not destroy the commits (they remain in the database). It destroys the uncommitted changes that existed at that moment in the index and in the working directory.

That is what cannot be undone, because it was never in .git/objects (lesson 09-01, table in section 1).

An important and reassuring exception: --hard does not touch untracked files. If you had a notes.txt that you never added, it is still there. What it sweeps away are the modifications to tracked files.

The --hard row is the one to memorise: it sweeps away two things at once, the commit and your work in progress. And only one of the two can be recovered.

They exist, and in two situations they are exactly what you want:

--keep is a well-mannered --hard: it moves the branch and updates the files that differ, but aborts if that would trample a local change. It is the sensible option when you want to go back and are not sure you have everything committed:

That error, here, is good news: it has just saved you.

--merge is similar but tries to merge the local changes into the destination. It is used mostly to abort a merge by hand.

Practical rule: when you are tempted to type --hard and are not sure, type --keep. If it works, there was nothing to lose; if it fails, you have just avoided the problem.

This is the recipe book. It is arranged from the smallest scope to the largest.

Ana has been trying things out in styles.css and wants to go back to how it was.

This one really does destroy, and with no net: uncommitted modifications are nowhere at all. Git does not even ask.

Bruno has run git add . and has accidentally swept in personal-notes.md.

You have lost nothing: the file is still modified in the working directory, it merely stops being staged.

Note the asymmetry, which is source of confusion number one:

git restore with no options acts on the working directory. With --staged, on the index. It is the opposite of what many people assume, and it is the reason git restore deserves a section of its own (section 6).

The most frequent case of all. Carla has committed and realised that the commit mixes two things together.

You have lost nothing. The commit is no longer on the branch, but all its content is staged. Now she can redo it:

If she also wants to choose again what goes into each commit, --mixed and git add -p (lesson 02-04):

That is the complete "I have mixed two things into one commit" flow, and it is the one used every day.

You do not need reset for this. --amend replaces the last commit (lesson 02-04), and with -m it does not even open the editor:

Remember that the hash changes: if it was published, this rewrites history.

Three commits off the branch. Before running it, two habits that cost five seconds:

With git branch backup-GT-241, the --hard stops being irreversible in any sense: the commits remain reachable from the backup. It is the same pattern as in lesson 09-01, section 5.2, and the one generalised in 09-04.

And if you have already done it without a backup: no matter, as long as they were not uncommitted changes.

This is the "throw away everything of mine and leave me like the server". Useful when your local copy has got hopelessly tangled and you know there is nothing of yours worth saving.

Check first what you are about to throw away:

If the first list is not empty, do not run the --hard without creating a backup branch first.

Here reset is not the answer. Rewriting a published branch forces you to force the push and destroys the work of anyone who has the previous version.

The answer is git revert (lesson 05-06): it creates a new commit with the inverse change, it rewrites nothing, there is no need to force, and there is a record of it.

The only exception: a published branch that is exclusively yours (your GT-241 working branch, which nobody else uses). There you can indeed rewrite and force with --force-with-lease, and that is lesson 09-03.

Here is the main source of confusion with reset, and it deserves a section of its own.

When you add a path, git reset does something completely different:

git reset <commit> -- <path> does NOT move the branch. It copies the state of <path> at <commit> into the index, and leaves the working directory untouched.

Why it cannot move the branch: moving HEAD to another commit is an operation on the entire repository. There is no such thing as "moving the branch for just one file". So when you give a path, Git understands that you want the other operation: filling the index from a commit.

A direct consequence: git reset <commit> -- <path> does not accept --hard.

Precisely because the --hard mode implies touching the working directory, and this form never does.

It is the way to stage the old content of a file, typically in order to undo only part of a commit:

The index now has the previous version of styles.css, staged. A git commit creates a commit that undoes only that part.

And if you also want the file on disk to change, the modern and far clearer form is git restore:

Picking up from lesson 08-03:

git rm --cached removes the file from the index (it stops being tracked) but keeps it on disk. It is the operation to perform when something got into the repository and you then added it to .gitignore. It is a close cousin of git reset -- <path>, but for stopping tracking the file rather than restoring its content.

Git 2.23 split the old git checkout into two commands with honest names: git switch for branches (lesson 03-02) and git restore for files. It is the tool you should be using every day, leaving reset for what genuinely involves moving the branch.

The equivalence table with the old forms, because you will see both in documentation and in forum answers:

git restore -p deserves a separate mention. It is the sibling of git add -p: it shows you each hunk of the diff and asks whether you want to discard it. It is the surgical way of undoing part of a change without losing the rest, and it avoids the "I am going to discard everything and redo it".

Perfect for removing debugging console.logs while keeping the real work.

Everything above has a safety net to some degree. This command has none at all, and that is why it deserves the most serious tone in the lesson.

git clean deletes untracked files. And an untracked file has never passed through .git/objects: there is no commit, no blob, no reflog, no fsck that can help. When git clean deletes it, it is deleted, just as with rm.

-n (or --dry-run) deletes nothing: it only lists. Read the whole thing. If something you care about shows up in that list, do not run the real command.

This habit is not optional. It is the difference between tidying up the project and losing the local configuration file you have been maintaining by hand for six months.

The usual uses:

-x is the one to look at twice. It deletes what .gitignore protects, and that is usually precisely where the things that are not in the repository but do matter to you live: .env with the local configuration, development credentials, test databases.

Option 4 (ask each) asks one by one. When there are many files and only some are surplus, it is the right way to do it.

The combination that circulates on the internet as "leave it all clean":

That leaves the directory exactly like a freshly made clone of that commit. And it sweeps away, without asking and with no possibility of recovery:

• All uncommitted changes to tracked files.
• All the new files you had not added.
• Everything ignored: .env, node_modules/, local configurations, test databases.

It is a legitimate command — in CI, in a container, in a throwaway repository — and a catastrophe on the machine of someone who has been working for two hours. Never paste it without having run git clean -ndx first and read the list.

git stash -u (lesson 05-04) also saves the untracked files, and it saves them as Git objects. With that, what you were about to delete moves into the database and therefore stops being unrecoverable. It costs one second.

Before an operation that moves HEAD substantially — reset, merge, rebase, pull — Git saves the previous position in a special reference:

So the immediate "undo" of a reset is:

Or, following the safe pattern:

Two warnings about ORIG_HEAD:

• It only saves one position, that of the last operation. If you do two resets in a row, the first one is lost. That is what the reflog is for, which saves the entire history of movements (lesson 09-04).
• It does not recover uncommitted changes. ORIG_HEAD is a commit hash: it puts the branch back where it belongs, not your work in progress.

It is the safety net for the next thirty seconds. For everything else, 09-04.

The right question is not "which command do I use to undo?", but "where is the thing I want to undo?". With that answer, the command is immediate.

And in table form, which is how it gets consulted in the moment:

The row that governs all the others is the "is it published?" one. If the answer is yes and the branch is shared, reset drops off the list and the only correct tool is revert.

Mistake 1: believing that reset --hard deletes commits. It does not delete them: it moves the branch. The commits are still in .git/objects and the reflog finds them (09-04). What it does destroy are the uncommitted changes.

Mistake 2: using --hard when --soft would have done. If all you wanted was to redo the commit, --soft keeps everything staged. --hard also sweeps away your work in progress.

Mistake 3: confusing git restore <f> with git restore --staged <f>. The first destroys the change on disk; the second only takes it out of the index and loses nothing. They are almost opposites.

Mistake 4: expecting git reset <commit> -- <path> to move the branch. It never does, and that is why --hard with paths gives an error. It is a different operation with the same name.

Mistake 5: running git clean -fdx copied from the internet. It deletes .env, local configurations and everything ignored, with no possibility of recovery. -n first, always.

Mistake 6: running reset on a shared branch and forcing the push. It destroys the work of anyone who had the commits. On published material, revert (05-06).

Mistake 7: using git reset --hard origin/main without checking what of yours is ahead. git log --oneline origin/main..HEAD costs a second and tells you exactly what you are about to throw away.

Mistake 8: forgetting that --hard respects untracked files. It is not a serious mistake, but it explains the "I ran reset --hard and this is still here": it was untracked.

Tip 1: when you hesitate between --hard and doing nothing, use --keep. It does the same thing, but aborts instead of trampling local changes.

Tip 2: git branch backup-<something> before any reset --hard. It costs two seconds and turns the operation into something trivially reversible.

Tip 3: use git restore and git switch instead of git checkout. The names say what they do and they prevent mistakes born of confusion.

Tip 4: git restore -p for removing the console.logs. Surgical, and it keeps the rest of the work.

Tip 5: git stash push -u before any clean-up. It turns the unrecoverable into the recoverable for one second of effort.

Tip 6: remember ORIG_HEAD. The immediate undo for a reset, merge, rebase or pull you have just regretted.

1. Create a repository with app.js and three commits. In the third one, also add styles.css.
2. Modify app.js without committing and create a new file notes.txt without adding it.
3. Run git reset --soft HEAD~1 and note down the output of git status --short and git log --oneline -1.
4. Undo it with git reset --hard ORIG_HEAD... and observe what has happened to your modification of app.js. Explain it.
5. Repeat the complete experiment with --mixed and with --hard, and fill in a table with three columns: log -1, the uncommitted change in app.js, and notes.txt.
6. Explain why notes.txt survives even --hard.

1. On a repository with four commits, where the third modified app.js, styles.css and index.html, try git reset --hard HEAD~1 -- app.js and explain the error.
2. Use git reset HEAD~2 -- styles.css and check with git status, git diff and git diff --cached which area the change has ended up in.
3. Commit. Check that you have undone only the styles.css part of the third commit and that the rest is still in the project.
4. Achieve the same result with git restore --source=... --staged --worktree and compare the state of the working directory in both cases.

1. In a test repository, create three situations at once: an unpublished commit, a change staged with git add, and a change on disk only.
2. Run git reset --hard HEAD~1.
3. Recover the commit using the reflog.
4. Try to recover the staged change with git fsck --lost-found and git cat-file -p.
5. Try to recover the change that was on disk only. Document why it is not possible.
6. Repeat the whole exercise having run git stash push -u beforehand and explain what changes.

Solution 1:

The commit has come off the branch and its content is staged (M and A in the first column). And there is a fine detail here: app.js appears only once because the index contains both the undone commit's content and your uncommitted modification still outside... in reality the modification of app.js is still in the working directory, and the index has the version from the undone commit. Check it:

Nothing has been lost: the two layers are intact and separate.

The branch has gone back to its place, but the modification of app.js has disappeared: --hard has overwritten it. ORIG_HEAD restores the branch's position, not your work in progress. It is exactly the warning from section 8.

notes.txt is not in the index: Git does not track it. reset operates on HEAD, the index and the files Git knows about; an untracked file is invisible to it. To delete it you need git clean (section 7).

Solution 2:

With a path, reset never touches the working directory or moves the branch; --hard implies both things, so it is contradictory. Git rejects it instead of doing something halfway.

The key point: the file on disk is still v3. Only the index has v1. That is why git diff (working tree vs index) shows the inverse change. And the branch has not moved:

app.js keeps v4, index.html keeps v3 (what c3 contributed), and only styles.css has gone back. A third of a commit has been undone.

Note, though: the file on disk was still v3 when you committed. The commit says v1 and the disk says v3, so now there is a pending modification. That asymmetry is precisely what restore avoids:

The index and the working directory agree. That is the practical difference: reset -- <path> only stages; restore --staged --worktree stages and writes to disk. For everyday use, restore is more predictable.

Solution 3:

Everything gone: the commit, the staged file and the modification on disk.

Recovered in full.

The git add saved it. On staging the file, Git created the blob and wrote it into .git/objects. The reset --hard removed the reference from the index, but the object stayed.

There is only one dangling object, the one from the add. The line CHANGE ON DISK ONLY does not exist anywhere in .git. Its hash was never calculated, it was never compressed, it was never written. Git cannot recover something it never knew about. The only real avenues would be your editor's local history (VS Code, IntelliJ and Vim with undofile keep it) or a filesystem backup.

Everything intact, including the untracked file, thanks to -u. The stash turned the three layers into hidden commits inside the database, and therefore into something recoverable even if the stash had been deleted (lesson 09-04).

One second of git stash push -u buys the difference between "I have lost two hours" and "nothing happened".

reset stops being frightening as soon as you understand that it does two things under the same name.

• git reset <commit> moves the branch. It does not delete commits: it rewrites a 41-byte file. The commits that stop being reachable remain intact in the database.
• The three modes are distinguished by how far they reach: --soft only moves HEAD; --mixed (the default) also rewrites the index; --hard also overwrites the working directory. Only --hard destroys anything, and what it destroys is uncommitted changes, not commits. It does not touch untracked files.
• --keep is the prudent --hard: it aborts instead of trampling your local work.
• git reset <commit> -- <path> is a different operation: it never moves the branch, it never touches the disk, it only fills the index. That is why --hard with paths is an error.
• For everyday work, git restore: --staged to unstage (it loses nothing), with no options to discard on disk (it destroys), --source to bring content from another commit and -p to do it hunk by hunk.
• git clean is the only command in this module with no safety net, because what was never committed is not in .git/objects. -n before -f, always; -x deserves reading twice; git stash push -u turns it all into something recoverable.
• ORIG_HEAD undoes the last reset, merge, rebase or pull. It only saves one position.
• And the decision, in one question: is it published? If not, reset, --amend or rebase -i. If it is and the branch is shared, revert (lesson 05-06), no exceptions.

That leaves the case the decision table dispatches with a "see 09-03": what to do when the thing that has got tangled is not inside your repository, but between your repository and the server. The rejected push, the divergent branches message, the colleague who rewrote the published history and left you with work hanging off a base that no longer exists.

All of that, and the closing of the promise we left open in lesson 04-05, in lesson 09-03: Resolving Divergence with the Remote.