In plain English, what does "git reset" do?

Question

I have seen interesting posts explaining subtleties about git reset.

Unfortunately, the more I read about it, the more it appears that I don't understand it fully. I come from a SVN background and Git is a whole new paradigm. I got mercurial easily, but Git is much more technical.

I think git reset is close to hg revert, but it seems there are differences.

So what exactly does git reset do? Please include detailed explanations about:

• the options --hard, --soft and --merge;
• the strange notation you use with HEAD such as HEAD^ and HEAD~1;
• concrete use cases and work flows;
• consequences on the working copy, the HEAD and your global stress level.

Gladiolus

Working link to A Visual Git Reference as of 24/Apr/2021. – Neurologist

git reset — mixed default/ same as git reset files remain in working directory — git reset — soft does not remove either tracked or untracked files, you can deal with these files manually either discarding them or keeping them in the staging directory. The files are not removed from the branch. git reset — hard removes all tracked files from the branch and you will not find these files either in the working directory or staging area. Untracked files will remain in the working directory. More – Conversational

Answer 1

In general, git reset's function is to take the current branch and reset it to point somewhere else, and possibly bring the index and work tree along. More concretely, if your master branch (currently checked out) is like this:

- A - B - C (HEAD, master)

and you realize you want master to point to B, not C, you will use git reset B to move it there:

- A - B (HEAD, master)      # - C is still here, but there's no branch pointing to it anymore

Digression: This is different from a checkout. If you'd run git checkout B, you'd get this:

- A - B (HEAD) - C (master)

You've ended up in a detached HEAD state. HEAD, work tree, index all match B, but the master branch was left behind at C. If you make a new commit D at this point, you'll get this, which is probably not what you want:

- A - B - C (master)
       \
        D (HEAD)

Remember, reset doesn't make commits, it just updates a branch (which is a pointer to a commit) to point to a different commit. The rest is just details of what happens to your index and work tree.

Use cases

I cover many of the main use cases for git reset within my descriptions of the various options in the next section. It can really be used for a wide variety of things; the common thread is that all of them involve resetting the branch, index, and/or work tree to point to/match a given commit.

Things to be careful of

• --hard can cause you to really lose work. It modifies your work tree.

• git reset [options] commit can cause you to (sort of) lose commits. In the toy example above, we lost commit C. It's still in the repo, and you can find it by looking at git reflog show HEAD or git reflog show master, but it's not actually accessible from any branch anymore.

• Git permanently deletes such commits after 30 days, but until then you can recover C by pointing a branch at it again (git checkout C; git branch <new branch name>).

Arguments

Paraphrasing the man page, most common usage is of the form git reset [<commit>] [paths...], which will reset the given paths to their state from the given commit. If the paths aren't provided, the entire tree is reset, and if the commit isn't provided, it's taken to be HEAD (the current commit). This is a common pattern across git commands (e.g. checkout, diff, log, though the exact semantics vary), so it shouldn't be too surprising.

For example, git reset other-branch path/to/foo resets everything in path/to/foo to its state in other-branch, git reset -- . resets the current directory to its state in HEAD, and a simple git reset resets everything to its state in HEAD.

The main work tree and index options

There are four main options to control what happens to your work tree and index during the reset.

Remember, the index is git's "staging area" - it's where things go when you say git add in preparation to commit.

• --hard makes everything match the commit you've reset to. This is the easiest to understand, probably. All of your local changes get clobbered. One primary use is blowing away your work but not switching commits: git reset --hard means git reset --hard HEAD, i.e. don't change the branch but get rid of all local changes. The other is simply moving a branch from one place to another, and keeping index/work tree in sync. This is the one that can really make you lose work, because it modifies your work tree. Be very very sure you want to throw away local work before you run any reset --hard.

• --mixed is the default, i.e. git reset means git reset --mixed. It resets the index, but not the work tree. This means all your files are intact, but any differences between the original commit and the one you reset to will show up as local modifications (or untracked files) with git status. Use this when you realize you made some bad commits, but you want to keep all the work you've done so you can fix it up and recommit. In order to commit, you'll have to add files to the index again (git add ...).

• --soft doesn't touch the index or work tree. All your files are intact as with --mixed, but all the changes show up as changes to be committed with git status (i.e. checked in in preparation for committing). Use this when you realize you've made some bad commits, but the work's all good - all you need to do is recommit it differently. The index is untouched, so you can commit immediately if you want - the resulting commit will have all the same content as where you were before you reset.

• --merge was added recently, and is intended to help you abort a failed merge. This is necessary because git merge will actually let you attempt a merge with a dirty work tree (one with local modifications) as long as those modifications are in files unaffected by the merge. git reset --merge resets the index (like --mixed - all changes show up as local modifications), and resets the files affected by the merge, but leaves the others alone. This will hopefully restore everything to how it was before the bad merge. You'll usually use it as git reset --merge (meaning git reset --merge HEAD) because you only want to reset away the merge, not actually move the branch. (HEAD hasn't been updated yet, since the merge failed)

  To be more concrete, suppose you've modified files A and B, and you attempt to merge in a branch which modified files C and D. The merge fails for some reason, and you decide to abort it. You use git reset --merge. It brings C and D back to how they were in HEAD, but leaves your modifications to A and B alone, since they weren't part of the attempted merge.

Want to know more?

I do think man git reset is really quite good for this - perhaps you do need a bit of a sense of the way git works for them to really sink in though. In particular, if you take the time to carefully read them, those tables detailing states of files in index and work tree for all the various options and cases are very very helpful. (But yes, they're very dense - they're conveying an awful lot of the above information in a very concise form.)

Strange notation

The "strange notation" (HEAD^ and HEAD~1) you mention is simply a shorthand for specifying commits, without having to use a hash name like 3ebe3f6. It's fully documented in the "specifying revisions" section of the man page for git-rev-parse, with lots of examples and related syntax. The caret and the tilde actually mean different things:

• HEAD~ is short for HEAD~1 and means the commit's first parent. HEAD~2 means the commit's first parent's first parent. Think of HEAD~n as "n commits before HEAD" or "the nth generation ancestor of HEAD".
• HEAD^ (or HEAD^1) also means the commit's first parent. HEAD^2 means the commit's second parent. Remember, a normal merge commit has two parents - the first parent is the merged-into commit, and the second parent is the commit that was merged. In general, merges can actually have arbitrarily many parents (octopus merges).
• The ^ and ~ operators can be strung together, as in HEAD~3^2, the second parent of the third-generation ancestor of HEAD, HEAD^^2, the second parent of the first parent of HEAD, or even HEAD^^^, which is equivalent to HEAD~3.

Needs

"you will use git reset to move it there." why don't you use git checkout to do so? – Gladiolus

@e-satis: git checkout will move HEAD, but leave the branch where it was. This is for when you want to move the branch. – Needs

So if I understand well, reset B would do : - A - B - C - B (master) while checkout B would do - A - B (master) ? – Gladiolus

@e-statis: No. Updated the answer to cover that. – Needs

Okayyyyyy. I just got something very important. You said "there is no branch pointing to it" and it bugged me. Now I get it. A branch is not a list a changes, it's just a pointer to somewhere in the history, isn't it? That's why SVN guy don't get it, we don't see it the proper way. Very useful post, hope you'll got plenty of rep from it. – Gladiolus

Oh, and there is only one HEAD, which has nothing to do with branches. Your HEAD is just the last commit, what ever branch in is into. You don't have one HEAD per branch. Or am I mistaken? – Gladiolus

@e-satis: Yes. A branch is merely a pointer to a specific commit - look at a file in .git/refs/heads and you'll see its contents is just an SHA1. – Needs

@e-satis: Yes, there is only one HEAD. It can be either a symbolic reference to the current branch (this is the normal state) or a direct reference to a given commit (by SHA1, like branches do - this is detached HEAD). More verbose explanation of this at your other question: https://mcmap.net/q/12189/-what-is-the-head-in-git – Needs

I think HEAD~3 is not necessarily always the same as HEAD^^^, particularly when HEAD has more than one parent. – Salomesalomi

@Salomesalomi j: It is. An excerpt from the documentation I linked: "A suffix ~<n> to a revision parameter means the commit object that is the <n>th generation grand-parent of the named commit object, following only the first parent. I.e. rev~3 is equivalent to rev^^^ which is equivalent to rev^1^1^1." – Needs

the docs are good even though it takes forever to read them and they're very dense and it takes forever to verify that they say it works like you already know how it works. Doesn't sound like the docs are good to me... – Hilversum

@Hilversum It takes me even longer to read something like this. The docs are complete, correct, and concise, which means they're dense. It's nontrivial information; you can never convey it in a short amount of time without summarizing and approximating. – Needs

@RosePerrone I appreciate what you're going for with your edit, and the diagram is nice. Careful, though; you rewrote a lot of text, made some things more clear and some things less (in my opinion, anyway), and removed the link to the canonical documentation. I've edited back, but kept a lot of what you added. – Needs

A much simple and understandable explanation is given by this SO answer: https://mcmap.net/q/11701/-what-39-s-the-difference-between-git-reset-mixed-soft-and-hard – Lottielotto

Please also add information about these commands: git reset and git reset -- .. – Reenter

@Reenter Most of that was already in there, for example that the default behavior is --mixed, and when I originally answered this is it was fairly clear the OP didn't have trouble with the notion of commit/path arguments, but I've added an extra section about the arguments. – Needs

@jefromi: +1ed. One of the best article I have read on git reset. I don't how you manage to write this kind of detailed article within 4 mins from the Question posted :)You must be super fast :D – Megass

Nice chart of HEAD using ~ and ^ – Melson

this is a very gr8 answer so much so that I was compelled to write this from someone who very rarely comments and who only understands half of the git puzzle. this alone helped me immensely understanding git. This also make me think that other commentors who did not show appreciation for this answer either are very lazy (I admit I am one but the answer is so gud that I had to write this) or really just do not understand git so much as to appreciate how gud this answer is. thanks for taking time to write this valuable answer. – Rf

@NitinBansal Yes, a simpler answer, but I really like this answer because of the details. I never really understood the difference between HEAD~2 and HEAD^2 before... – Lithe

Answer 2

Remember that in git you have:

• the HEAD pointer, which tells you what commit you're working on
• the working tree, which represents the state of the files on your system
• the staging area (also called the index), which "stages" changes so that they can later be committed together

Please include detailed explanations about:

--hard, --soft and --merge;

In increasing order of dangerous-ness:

• --soft moves HEAD but doesn't touch the staging area or the working tree.
• --mixed moves HEAD and updates the staging area, but not the working tree.
• --merge moves HEAD, resets the staging area, and tries to move all the changes in your working tree into the new working tree.
• --hard moves HEAD and adjusts your staging area and working tree to the new HEAD, throwing away everything.

concrete use cases and workflows;

• Use --soft when you want to move to another commit and patch things up without "losing your place". It's pretty rare that you need this.

--

# git reset --soft example
touch foo                            // Add a file, make some changes.
git add foo                          // 
git commit -m "bad commit message"   // Commit... D'oh, that was a mistake!
git reset --soft HEAD^               // Go back one commit and fix things.
git commit -m "good commit"          // There, now it's right.

--

• Use --mixed (which is the default) when you want to see what things look like at another commit, but you don't want to lose any changes you already have.

• Use --merge when you want to move to a new spot but incorporate the changes you already have into that the working tree.

• Use --hard to wipe everything out and start a fresh slate at the new commit.

Grubman

That's not the intended use case for reset --merge. It doesn't perform a three-way merge. It's really only for resetting out of conflicted merges, as described in the docs. You'll want to use checkout --merge to do what you're talking about. If you want to move the branch as well, I think the only way is to follow up with some checkout/reset to drag it along. – Needs

@Jefromi » Yes, I didn't phrase that very well. By "a new spot" I meant "a fresh place where you don't have the conflicted merge". – Grubman

Ah, I see. I think the important thing here is that unless you really know what you're doing, you probably don't ever want to use reset --merge with any target besides (the default) HEAD, because in cases besides aborting a conflicted merge, it's going to throw away information that you could otherwise save. – Needs

Please add information about these commands: git reset and git reset -- .. – Reenter

@John I did a git reset mixed to revert a commit but I really should have done git reset--soft. Now I cannot see the files in git status. Help? – Ratha

Answer 3

The post Reset Demystified in the blog Pro Git gives a very no-brainer explanation on git reset and git checkout.

After all the helpful discussion at the top of that post, the author reduces the rules to the following simple three steps:

That is basically it. The reset command overwrites these three trees in a specific order, stopping when you tell it to.

1. Move whatever branch HEAD points to (stop if --soft)
2. THEN, make the Index look like that (stop here unless --hard)
3. THEN, make the Working Directory look like that

There are also --merge and --keep options, but I would rather keep things simpler for now - that will be for another article.

Benge

it only took me 13 years of writing code to finally sit down and understand these concepts – Ghyll

Answer 4

TL;DR

git reset resets Staging to the last commit. Use --hard to also reset files in your Working directory to the last commit.

LONGER VERSION

But that's obviously simplistic hence the many rather verbose answers. It made more sense for me to read up on git reset in the context of undoing changes. E.g. see this:

If git revert is a “safe” way to undo changes, you can think of git reset as the dangerous method. When you undo with git reset(and the commits are no longer referenced by any ref or the reflog), there is no way to retrieve the original copy—it is a permanent undo. Care must be taken when using this tool, as it’s one of the only Git commands that has the potential to lose your work.

From https://www.atlassian.com/git/tutorials/undoing-changes/git-reset

and this

On the commit-level, resetting is a way to move the tip of a branch to a different commit. This can be used to remove commits from the current branch.

From https://www.atlassian.com/git/tutorials/resetting-checking-out-and-reverting/commit-level-operations

Anet

Answer 5

Please be aware, this is a simplified explanation intended as a first step in seeking to understand this complex functionality.

May be helpful for visual learners who want to visualise what their project state looks like after each of these commands:

---

For those who use Terminal with colour turned on (git config --global color.ui auto):

git reset --soft A and you will see B and C's stuff in green (staged and ready to commit)

git reset --mixed A (or git reset A) and you will see B and C's stuff in red (unstaged and ready to be staged (green) and then committed)

git reset --hard A and you will no longer see B and C's changes anywhere (will be as if they never existed)

---

Or for those who use a GUI program like 'Tower' or 'SourceTree'

git reset --soft A and you will see B and C's stuff in the 'staged files' area ready to commit

git reset --mixed A (or git reset A) and you will see B and C's stuff in the 'unstaged files' area ready to be moved to staged and then committed

git reset --hard A and you will no longer see B and C's changes anywhere (will be as if they never existed)

Durante

Answer 6

Checkout points the head at a specific commit.

Reset points a branch at a specific commit. (A branch is a pointer to a commit.)

Incidentally, if your head doesn’t point to a commit that’s also pointed to by a branch then you have a detached head. _{(turned out to be wrong. See comments...)}

Borderland

Not to nitpick, but (yes, in fact it is nitpicking but let's add it for completion) your 3rd sentence is technically false. Let's say your HEAD is pointing at branch B which is in turn pointing to commit abc123. If you now checkout commit abc123, your HEAD and branch B are both pointing to commit abc123 AND your HEAD is detached. Committing at this point will not update branch B's position. You could have said "if your head doesn’t point to a branch then you have a detached head" – Chaker

@RomainValeri What will committing do in that circumstance? – Borderland

Committing would create commits which aren't referenced by any branch, and branch B would keep on pointing to the same commit abc123 even after you committed multiple times after that. It implies that these commits would become candidates for garbage collection when HEAD stops pointing at the last commit in this 'wild' series of commits. – Chaker

Answer 7

I don't always do git reset, but when I do, I look at this:

* 444668f (HEAD -> main) C
|
* c3739b7 B
|
* 207e8a1 A
|
* 38fab46 Initial commit


git reset --hard 207e8


* 207e8a1 (HEAD -> main) A
|
* 38fab46 Initial commit


To retrieve the changes, use --soft instead

HEAD moved to A (main too, because HEAD points to main). git reset doesn't "reset" B and C. You still can see B and C with the --reflog option of git log:

git log --graph --oneline --all --reflog

Warning

Before you do git reset,

• If you have unstaged changes:

  • With --hard, it will get discarded
  • With --mixed (default), it will get mixed with staged changes and the retrieved commits changes

• If you have staged changes:

  • With --hard, it will get discarded
  • With --mixed, it will get mixed with unstaged changes and the retrieved commit changes
  • With --soft, it will get mixed with the retrieved commits' changes

To get rid of them, you can use git stash, but I prefer to just create a new branch and create a separate commit for the staged and unstaged changes there. Then use git rebase + git reset when I need them back.

Gober