Introduction to Git Bisect: Find Commits that Introduced a Bug

Even though I don't have years of professional programming experience, there has been a number of times where a bug is reported on my application and I cannot find out what change introduced it. This ends up being extremely frustrating and hard to work around. Once I discovered git bisect, I never experienced this frustration again.

Git Bisect

's documentation has a great description:

"This command uses a binary search algorithm to find which commit in your project’s history introduced a bug. You use it by first telling it a "bad" commit that is known to contain the bug, and a "good" commit that is known to be before the bug was introduced. Then git bisect picks a commit between those two endpoints and asks you whether the selected commit is "good" or "bad". It continues narrowing down the range until it finds the exact commit that introduced the change."

As it says,

git bisect

This is especially useful in large projects with tens or hundreds of commits a day. Finding the specific commit where a bug was introduced can make fixing it increasingly simpler. Understanding the changes that caused the issue makes it easier to solve it.

How it works

The first step in using

git bisect

abc123

Then you can start the

git bisect

git bisect start
git bisect bad
git bisect good abc123

At this point,

git bisect

If the bug exists, you can run:

git bisect bad

If it does not, run:

git bisect good

This process is then repeated until it finds the commit that introduces the bug. You will see an output similar to (along with a description of the commit):

def456 is the first bad commit

At this point you have found the commit, can view the changes that it introduced, and hopefully squash that bug 🐞!

You can exit the

git bisect

git bisect reset

Example

I've prepared an example application in which we can go through this together. It is a simple React app bootstrapped with . You can see the code for this example .

Here is what the application looks like:

Pretty simple, just has some text as a form of a landing page.

However, originally there was a cool React logo that was spinning on the page! This was not supposed to be removed but was. It looked something like this:

Now I try to keep my commit messages clear on what they are doing, so that finding where this happened would be simple but sadly this doesn't hold up in large projects.

Commit messages sometimes end up being less than helpful:

With this project, I did not do a great job of writing good commit messages. Finding the commit that removed the logo will be a lot of manual work as I will have to go through every commit's changes and look for where it is removed. However, with

git bisect

First I find a commit where the logo is present. Because this is a small project I went to the first commit of the project (

66f768475cd0543370e086d6bea3a06bbc0dd2e0

I then start a `git bisect` session:

git-bisect-example on master
❯ git bisect start
❯ git bisect bad
❯ git bisect good 66f768475cd0543370e086d6bea3a06bbc0dd2e0
Bisecting: 2 revisions left to test after this (roughly 1 step)
[037a419be3488a3d2208abecdc49bda251b871a1] made some more changes :)

It brought me to the commit with the hash

037a419be3488a3d2208abecdc49bda251b871a1

❯ git bisect bad
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[5e35e0026935c3c3808e87b5691d22d4650bd145] changed some text

This commit has the logo! I mark it as good:

❯ git bisect good
037a419be3488a3d2208abecdc49bda251b871a1 is the first bad commit
commit 037a419be3488a3d2208abecdc49bda251b871a1
Author: Boston Cartwright
Date:   Mon Jun 8 12:48:44 2020 -0400
    made some more changes :)
 src/App.js | 1 -
 1 file changed, 1 deletion(-)

As we can see by the above output,

git bisect

037a419be3488a3d2208abecdc49bda251b871a1

Obviously with larger repositories and many more commits this can be a big time saver to find which commit introduces the bug. I have used `git bisect` a number of times now and it has been a huge help.

Let me know what you think!