Tips and Tools: git bisect

One of the best tools available for a developer is git. Git is awesome it allows you to track work changes. Walk forwards and backwards in a commit timeline, branch out and build features indipendently and collaborate with others.

Today we will take a look at one feature of git, I rarely see people use. And its definitely not because its a niche, since most of the time people go the long and hard way around instead of using it. That feature is BISECT.

Lets start with a scenario. Say you are building website, you start with an empty page and initialize a repository. And you add you only core feature.

A simple RED <h1>, tag as seen below:

Screenshot 2023-03-09 at 6.28.43 PM

Thenm you add your first actual feature. A <p> tag with some text, as below.

Screenshot 2023-03-09 at 6.33.41 PM

Pretty simple stuff. Now lets fast forward a bit.. Overtime, a lot of features get added from various developers. And some time later our application looks like this:

Screenshot 2023-03-09 at 6.34.06 PM

But wait... we have a bug! our RED header in now GREEN. Disclaimer:

Now in our very simple scenario, iti s just a css style rule that needs to be corrected. We can just go ahead and fix it easily. But what about more complex scenarios? What if it is a weird change that occured as a side effect? So do not take the example at face value.

You will say, we have git! We can travel back in commit history, until we find the commit that introduced the bug. Then we can see what changed were done and look around for exactly the thing that went wrong. ....and that is correct.

So we can do a git log/reflog get the commit hashes, and start checking them out one by one, going backwards until we find the issue....

That will work... Buuuut, what if the commit history is long? What if you have 25-30-40 commits and a bug went unoticed for more than it should? Are you willing to go back 40 commits manually?

Here we have 8.. and still its a bit too much.

Screenshot 2023-03-09 at 6.15.27 PM


No worries!! git bisect to the rescue! What git bisect does is that it receives range of commits, marked by:

  • A good one, which is the START, meaning that our application worked fine there.
  • A bad one, which is the END, meaning that the bug is present in that commit.

Warning a bad commit means simply that the bug is present, its not the one that necessarily introduced it!

We can start a bisect with: git bisect start

After that, we will see that a good and bad commit are required as our START and END. We can enter those with:

START: git bisect good HASH

END: git bisect bad HASH

As seen below:

Screenshot 2023-03-09 at 8.03.11 PM

In our case we selected as a good commit the one where the h1 tag was first added, since we know that the feature worked as intented there, and as a bad on the current one - HEAD. Since we can see the bug here.

The fun part part.

After that, in a Divine & Conquer fashion, git will checkout the middle commit between those two.

As seen below, with green is our START, red our END and pink the CURRENT checked out hash we are bisectig.

Screenshot 2023-03-09 at 6.15.27 PM 3

At that state, we can check our app and see if the bug is present. Depending if it is or not, we can mark the commit as bad or good. We do this by entering:

git bisect good OR git bisect bad

If the commit is bad, that means that it was introduced earlier in history including the one we are in. That means it will checkout the middle commit between CURRENT and our START, and it will turn that commit into the END.

Screenshot 2023-03-09 at 6.16.24 PM

If it is a good commit it will checkout out the middle commit of the later history whilst turning CURRENT into the START. In our example, the bug was not present, so we marked the commit as good.

Screenshot 2023-03-09 at 7.35.20 PM

This process will repeat itself, until we zero down on the commit that introduced the bug. Next step:

Screenshot 2023-03-09 at 6.15.27 PM 4 2

Screenshot 2023-03-09 at 6.16.49 PM

In our case, since the bug is present we mark the commit as bad with git bisect bad

Screenshot 2023-03-09 at 6.15.27 PM 4 3

Screenshot 2023-03-09 at 6.17.15 PM

Now that is a good commit! so git bisect good

When finished wit the process and there are no more commits to bisect. We will get a message with the commit hash, the author and the change history. So we can start narrowing down the bug inside the code.

Screenshot 2023-03-09 at 6.17.42 PM

...and that is how bisect works!

Thanks for reading!

Contact Me