How to find an old and tricky bug by using Git

We, who write code for a living, have all faced a situation where we try to track down a bug that is hiding better than Jerry when he did something painful to Tom. This is especially true if you work on a project with more people or teams. Where is the bug!?

That’s where git bisect can help us! Let me first introduce a typical situation where this tool can come in handy.

Story time

Imagine that you work for a large, high-tech Fortune 500 company.

You work on a calculator project, where you and your team own subtraction. You don’t care about additions, multiplication, or any of that. There are tens of people working in the same codebase as you, and there are tens of new commits to the main branch daily. This is very similar to our reality in Outreach.io where our teams work on a project, with focus mainly on some area of the application.

After months of hard work, you and your family leave for a well deserved vacation to a beautiful beach resort for one or two weeks.

After coming back from vacation, the first thing you do is make yourself a coffee and tell your colleagues how awesome your vacation was. You mention that once you’re older and rich, you will definitely buy some property there.

Then you open your calculator app and find out that subtraction doesn’t work. After debugging for several hours with no results, you ask your colleagues if they know what’s going on, again with no results.

What is binary search

Before we jump to git bisect, we should first understand what binary search is since git bisect operates on this algorithm.

Imagine that you want to find a specific page in your favorite book. Let’s say page number 246. How do you find this page?

I guess you wouldn’t open the first page, then the second, then the third until you reach page 246.

The binary search in this example is quite simple. You open the book somewhere in the middle, let’s say it’s going to be page number 323. The current page number is greater than the desired page number 246, therefore, the page you are searching for is somewhere in the left part of your book. So you open the left part of the book again somewhere in the middle and repeat the process until you find page 246.

Git bisect

Our goal now is to find the exact commit where the bug was introduced, as debugging doesn’t bring any fruit.

You know that when you were leaving for your vacation, the product worked just fine and now when you are back, it doesn’t. Therefore you have a timeline in which the bug has been introduced.

Timeline of commits where the bug must have been introduced

To start the git bisect, head to your project’s root repository and type the following command in your favorite command line app.

git bisect start

This will start the bisect and is now awaiting defining the timeline in which we are looking for the bug. You can simply mark the bad (app is not working on this commit) and good (app is working on this commit) commits by writing following commands with commit hashes. In our case, I will use the commit hashes from the image above.

git bisect good e3ff7e0
git bisect bad ad53b7f

After defining where bisect should be searching, it will checkout the commit somewhere in the middle. Now you should test your app manually to reproduce the bug.

git bisect checking out a commit somewhere in the middle of the timeline

If the app is working as desired, you can tell bisect that this commit is fine by typing following:

git bisect good

Notice how we don’t need to specify any commit hashes now as git bisect knows what commit is checked out.

Bisect will now checkout a commit somewhere in the middle of remaining commits.

bisect checking out in a middle of remaining commits

In our case, we were able to reproduce the bug now, so we will mark this commit as bad.

git bisect bad

You will repeat these steps, until you will finally find the exact commit, which introduced the bug. Then it should be much easier to find the issue, as you will know where to look.

When you are all done searching for the buggy commit, you can reset your git instance by typing following:

git bisect reset

Not a magic tool

Git bisect will not find the bug for you and if you can not reproduce the issue, it won’t be of any use either.

It is not a magic tool that should be used in every situation. You can use it in a “last resort” situation, when you are actually lost, but you know how to repro your bug and if you know in what timeframe approximately the bug appeared.

Conclusion

Git bisect is a powerful tool that can help you identify the commit that introduced a bug in your codebase. By following the steps outlined in this article, you can use Git bisect to quickly and efficiently locate the problematic commit and fix the issue. If you have any questions or feedback, please feel free to leave a comment below.