Git Bisect: How This Git Command Can Help with Bug Resolution

Learn how to use Git's versioning structure and binary search to find the commit that introduces a bug.

Sometimes, even when you're extra careful, bugs or other unexpected behaviors can wound up in your project and they're not always detected immediately and this can make the task of solving those bugs much harder. Git Bisect is a Git tool that can help you to track down the exact commit where the issue started, reducing the amount of code you have to review and making the whole bug squashing process less complicated.

Before we begin…

If we want to make use of Git Bisect we must have some knowledge about it, and the project must be already using it. If you still don't know what Git is or you're not using it in your projects yet, check out this article to have a nice overview of the information and reasons you need to start using it!

What is Git Bisect?

Git Bisect is a Git command that allows us to use Git's version control structure to search for and identify the root cause of a specific behavior in a codebase.

While this behavior doesn't necessarily have to be a bug, we'll refer to it as a "bug" from here on out, as this is the most common use case and simplifies our discussion.

This command uses a binary search algorithm to efficiently traverse a series of commits in the project, making it faster and more effective to pinpoint the specific commit where the bug was introduced.

In a nutshell, you need to provide the command with two starting points: the ID of a “good” commit and the ID of a “bad” commit. With this information, Git will identify the range in which the bug was introduced and, with your input, will narrow down the commits within this range until it finds the first “bad” commit.

Since Git Bisect is a built-in Git tool, it is independent of the programming language, technologies, frameworks, or Git platform you are using in your project. As long as your project is managed with Git, you can use Git Bisect to help you identify the problematic commit.

What is the main advantage of using Git Bisect?

Bugs are an unavoidable part of software development. No matter how careful the team is or how many precautions they take—such as regular code reviews and rigorous quality control for new features—small problems are bound to occur from time to time.

These small problems, or bugs, are not always immediately detected. Sometimes they can remain dormant in a feature that isn’t widely used or within a very specific use case, and it might take some time before someone stumbles upon them. When that elusive bug is finally discovered, the way to fix it—or even its origin—may not be immediately clear. It can be quite challenging to find the root cause of a bug, especially in cases where it went undetected for a while, leaving us unsure of which code change might have introduced it.

This is where Git Bisect comes in handy. If we have, or can find, a point in the past—meaning an older commit—where the bug did not exist, we can use this command and its binary search algorithm to pinpoint the exact commit where the problem started. Once we know the specific commit where the issue was introduced, we can narrow our focus significantly. Instead of sifting through the entire project’s codebase, we can concentrate only on the changes introduced in that commit, making it much easier to find the root cause of the bug.

How does Git Bisect Work?

As I mentioned before, Git Bisect uses a binary search algorithm to find the specific commit that introduced a bug.

When we run Git Bisect, we need to provide a reference to a “good commit” and a “bad commit.” A “bad” commit is one where the bug is present, and a “good” commit is one where the bug does not occur. With these two starting points, Git will check out a third commit, located approximately in the middle of the given range. At this point, we need to test our code again to check for the bug's presence, and then tell Git whether this commit is “good” or “bad.”

After we do this, Git will check out a new commit, again in the middle of the updated range, and the process will repeat until we find the first commit where the bug appears.

The images above provide an example of how Git Bisect interactions look. Starting with “good” and “bad” commits, we search in progressively smaller intervals until we find the original commit that introduced the bug.

How to use Git Bisect?

Several checkouts will occur during the use of the Git Bisect command. So, before you start, I recommend stashing or committing any ongoing changes in your working directory. If you just want to test out the command, I have a simple repository that you can clone and use as a tutorial or test. It’s the same repository I used to create the images above, and although it’s very simple, it can help you understand how Git Bisect works in practice.

With all that said, we can finally start by running the following command in your terminal:

• git bisect start

Then we need to provide the starting points, meaning a “good commit” and a “bad commit”.

• git bisect bad BAD-COMMIT-IDENTIFIER

• git bisect good GOOD-COMMIT-IDENTIFIER

A commit identifier is, as the name suggests, something that allows you to single out a particular commit. We typically use the hash (or ID) of each commit, but you could also use a tag. If the commit you want to mark as either good or bad is the one where you are currently checked out, you can omit the identifier.

With this information, Git Bisect will start running and will check out a new commit in the middle of the interval between the two initial commits you provided. At this point, test your project to determine whether the bug still exists, and then flag the current commit as either “good” or “bad.”

• git bisect good 

or

• git bisect bad

From here on out, the process will continue as explained in the previous section. At each step, you’ll be checked out to a commit within the remaining interval. You’ll need to test the code and mark that commit as either good or bad. This process will repeat until you identify the first bad commit.

Once you know which commit introduced the bug, you can analyze the changes in that specific commit to find the root cause of the issue.

If you want to learn more about the Git Bisect command, I recommend reading the official documentation.

Happy Bug Hunting with Git Bisect!

I'll admit, it's very likely that you won’t use Git Bisect on a daily basis, but I still believe it’s a valuable tool to have in your “utility belt.” It has already helped me greatly, especially when dealing with large and complex codebases with multiple contributors, where simultaneous changes to the same features and files can occur.

I hope that the next time you encounter one of those pesky bugs that no one seems to know how or where it started, you’ll remember this article and be able to harness the power of Git Bisect to solve the challenging bug more quickly and efficiently.

Let's connect on social media, follow us on LinkedIn!

Article written by Lucas Dias, and originally published at https://kwan.com/blog/git-bisect-how-this-git-command-can-help-with-bug-resolution/ on August 12, 2022.

See you in the next article!