konrad_126

Posted on Jan 8, 2019 • Edited on Oct 25, 2020

Git Reset --Hard git reset --explain

#git #reset

Reset is probably one of the least understood git commands with the addition of having a bad reputation for being dangerous. There is a valid reason for both of these claims: yes, the reset command is a bit harder to understand and in some cases, it can be dangerous. But, it is not all that hard. So in this post, I will give my best to present you with a clear and distilled tutorial to the reset command. To make it short and not too overwhelming I have abstracted the non-essential details and simplified some things, but if you want to know more on git's internal workings you can also check my Understanding Git series for more details of some stuff presented here.

Git Trees

Before we dive into the reset command we need to take a look at what is called the trees of git: Working Directory, Staging Area and the Repository.

You can think of them as areas where changes can reside from git's point of view:

Working Directory - your project files on your filesystem
Staging Area - a preview of the next commit
Repository - datastore where git keeps all (past) commits.

The reset command operates on these threes/areas, but first, let's take a look how do add and commit command that we use daily, affect these areas.

Say we have a web app and we do some refactoring on our index.php file. Changes that we make are reflected in the Working Directory:

We can confirm this by running git status:

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)
modified:   index.php

Now we move those changes to the Staging Area by using the add command:

And running the status command now will tell us:

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)
modified:   index.php

Because the status command sees that we have the same version of index.php file both in Working Directory and in the Staging Area, but not in Repository.

To add it there, we use the commit command:

And now the Working Directory, Staging Area and Repository all contain the same version of index.php, and running git status will tell us that there is:

nothing to commit, working tree clean

So, the way the status command works is that it compares file versions in Working Directory, Staging Area and Repository and if there are different than there are files to be staged/committed.

Let's say we now refactor the index.php file some more and do the whole add/commit cycle again.
Now our Working Directory, Staging Area and the Repository all contain the new second version of our index.php file.

But what about the first version? If you remember, we did say that the Repository keeps all previous commits, so the first version of index.php file is still there:

To keep track which version of our index.php file is the current one, Repository has a special pointer called HEAD that points to the current version (and the status command only looks at the current version that HEAD is pointing to when comparing it to the Staging Area's version).

And now that we have that covered we can finally go to our reset command and see how it works by manipulating the content of these areas.

reset --soft

This first mode of reset command will only do one thing:

move the HEAD pointer.

In our case, we will move it to the previous commit (the first version of index.php) by doing: git reset --soft HEAD~1

The trees of git now look like this:

And if we would to run git status we would see a familiar message:

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)
modified:   index.php

So, running git reset --soft HEAD~1 has basically undone our last commit, but the changes contained in that commit are not lost - they are in our Staging Area and Working Directory.

reset - mixed

The second mode of the reset command will do two things:

move the HEAD pointer
update the Staging Area (with the content that the HEAD is pointing to)

So, the first step is the same as with the --soft mode. The second step takes the content that HEAD points to (in this case, it is version one of the index.php file) and puts it into the Staging Area.

So, after running git reset --mixed HEAD~1 our areas look like this:

And if we would to run git status now we would again see a familiar message:

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)
modified:   index.php

So, running git reset - mixed HEAD~1 has undone our last commit, but this time the changes from that commit are (only) in our Working Directory.

reset --hard

And now for the notorious hard mode. Running reset -- hard will do three things:

move the HEAD pointer
update the Staging Area (with the content that the HEAD is pointing to)
update the Working Directory to match the Staging Area

So, the first two steps are the same as with --mixed.The third makes the Working Directory look like the Staging Area (that was already filled with what HEAD is pointing to).

So, after running git reset --hard HEAD~1 our areas look like this:

And running git status will give us:

nothing to commit, working tree clean

So, running git reset - hard HEAD~1 has undone our last commit and the changes contained in that commit are now neither in our Working Directory or the Staging Area. But they are not completely lost. Git doesn't delete commits from Repository (actually, it does sometimes, but rarely), so this means our commit with the second version is still in the Repository, only it is a bit harder to find (you can track it by looking at something called reflog).

So, what is then with this reputation of reset being dangerous? Well, there is one case where some changes could be permanently lost. Consider a scenario where after the second commit you make some more changes to your index.php file, but you don't stage and commit them:

And now you run git reset --hard HEAD~1:

Since the reset command will overwrite the content of your Working Directory to match the Staging Area (that is made to match HEAD) and you never staged and committed your changes (there is no commit with those changes in the repository), all those changes will now be lost in time... Like tears in the rain.

The danger of hard reset lies in the fact that it is not Working Directory safe - meaning it won't give you any warning if you have file changes in your Working Directory that will be overwritten (and lost) if you run it. So be (extra) careful with a hard reset.

And there you have it: the reset command. I hope I did a good job explaining it and that you'll agree it is not that hard after all. And, yes it can be dangerous but only if used with --hard option.

As said in the beginning if you would like to know more on the inner workings of git, you can check my Understanding Git series, and if you want a more in-depth explanation on the reset command you can check the Reset Demystified chapter from git pro book.

Appendix:

In the examples, we used we used HEAD~1 as an argument for the reset command. As you probably already know every commit in git has a unique identifier called a checksum, and we can use it as an argument for the reset command too

To make examples simpler we only had one file that we edited and committed, in reality, we often commit multiple files, so a specific commit holds different versions of multiple files.

The special HEAD pointer usually doesn't point directly to a commit (as shown in examples for simplicity) but to a branch pointer that then points to a specific commit

Top comments (6)

Mario DeLaPaz • Jan 9 '19

Very well written post. I found it easy to follow and understand. I myself had trouble fully understanding what reset --hard did, instead I would just follow the instructions of the SO answers and forum posts that just told me to do it.

The more I use and understand git, the easier it gets.

Jesse Phillips • Jan 9 '19 • Edited

I found two dangerous commands.

git reset --hard
git clean

All other commands can be run and git will stop if unsaved changes would need to be changed until force is used.

Even clean is only dangerous if you configure it to be and if you're using it force might be a habit

David Van Couvering • Oct 14 '20

Hey, Konrad, thanks for this! You explain things very very well, with great graphics. I tried to follow your link to your Understanding Git series and got a 404. Can I find it anywhere?