Git Bisect

One of the coolest tools in Git is called git bisect. Git bisect is a tool that allows us to easily make use of a technique known as ‘a lion in the desert' which is a binary search. This is a solution for finding bugs, generally speaking regression bugs (something that worked before but doesn’t work anymore). Normally, the quickest way to find a fix to this kind of bug is to find an earlier version where it was still working and then work forward through the versions until you find when the bug starts.

Let’s assume I have a website with a feature that used to work in the past, but today no longer works. I’m currently in the branch called master and the latest version is not working. But, by using the following command I can go back to a later version:

git checkout HASHNUMBER

The hashnumber is essentially the name of the latest push, and now I can see that in the previous version the feature in question worked as expected. In other words, somewhere between the new version and the previous one, something went wrong.

^{Git log example. The current version is not working and has a bug. Then, an older version that works.}

So in this example, if I run:

git checkout 588fba7

I’ll go back to the previous version in the code where I’ll see that the problematic feature works as expected. Obviously many features that were developed since are missing, but the feature in question works. I can run git diff on the working version and the current version, but generally there will be significant differences in the code. What I need is the last version where the feature was working. Then I can compare it to the first version where it wasn’t working and easily see what went wrong.

What a lot of programmers do here is to slowly go forward and check the bug as they go. But this is not really a very efficient method. Some programmers will use the ‘lion in the desert’ method—they’ll take a version in the middle thereby decreasing the range of versions where the bug may be. But, there’s an even better method which is also automatic called git bisect. This method is also quite simple. The basic usage of git bisect is:

git bisect start BADCOMMIT GOODCOMMIT

The BADCOMMIT is the hash of the version that doesn’t work. If this happens to be the current version of the master then it would be called master, or the name of the branch. The GOODCOMMIT is the version where the feature works.

For example:

git bisect start master 588fba7

The moment I run git bisect, Git will try to find the problematic version. Git will automatically go over a version between the known working version and bad version and will ask me if the feature is working. If it’s not, I type:

git bisect bad

Or, if it is working I type:

git bisect good

Git will continue to check versions until it finds the version in which the feature first stopped working.

^{The Git bisect process. Each time we need to type git bisect good or git bisect bad, depending on whether or not the feature works.}

Once the first non-working version is found, I can easily run diff between that version and the one that comes directly after it and find out what went wrong. At any given moment I can exit out of the bisect with:

git bisect reset

A lion in the desert is not the most efficient method to find bugs but sometimes it’s a good solution. In these instances, git bisect make the process much easier and faster since Git uses the most efficient way to ‘dissect’ the desert to find the lion. Of course, this also helps prevent human error. So now that you know about it, I highly recommend using it.

About the author: Ran Bar-Zik is an experienced web developer whose personal blog, Internet Israel, features articles and guides on Node.js, MongoDB, Git, SASS, jQuery, HTML 5, MySQL, and more. Translation of the original article by Aaron Raizen.