Find That Bug Fast: A Developer’s Guide to Git Bisect

Every developer knows the nightmare: You pull the latest code, and suddenly, your application is broken. Your API is throwing 500 errors, or your frontend refuses to load. You check the commit history and find hundreds of changes since the last time you know it worked.

Where do you even begin?

You could manually check each commit, but that's a slow and tedious process. A much better solution is to use git bisect.

This powerful Git command can pinpoint the exact commit that introduced a bug in a matter of minutes. It's a lifesaver for debugging, and once you learn it, you'll wonder how you ever worked without it.

---

What Is Git Bisect?

git bisect is a built-in command that uses a binary search algorithm to find the specific commit that introduced a bug. Instead of you having to manually check every single commit, Git automatically does the heavy lifting.

Think of it like this:

Imagine you have 200 commits to search through. Manually checking each one would be a monumental task. But with git bisect, the process is cut down dramatically.

• You start with 200 commits.

• Git checks the middle commit (commit #100).

• If that commit is good, you only have 100 commits left to search.

• Git checks the middle of those (commit #150).

• If that's bad, you're down to a search space of just 50 commits.

This process continues, cutting the number of commits in half each time. For 200 commits, you only need to run about 8 tests (log_2(200)approx8) to find the culprit. This efficiency is what makes git bisect so incredibly effective.

---

How to Use Git Bisect: A Practical Guide

I recently came across this tool in a newsletter from Tech With Tim and decided to try it out for myself. I was amazed at how quickly it worked! Here's a step-by-step guide based on my own experience.

Let's walk through the steps with a practical example.

Imagine your application's tests passed last week on a commit with the hash a1b2c3, but today's latest commit, HEAD, is broken.

Step 1: Start the Bisect Session

First, navigate to your repository in the terminal and start the bisect process:

git bisect start

Step 2: Mark the "Bad" and "Good" Commits

Now, you need to tell Git which commits are "bad" (broken) and "good" (working).

Mark the current broken commit as "bad":

git bisect bad HEAD

Then, mark a known working commit as "good". You can use a commit hash, a branch name, or a tag. In our example, we'll use the hash from last week:

git bisect good a1b2c3

Step 3: Git Does the Work

Once you've marked the good and bad points, Git will automatically check out a commit roughly halfway between the two.

Your terminal will display a message like this:

Bisecting: 90 revisions left to test after this (roughly 7 steps)
[commit_hash] a brief description of the commit

At this point, you need to test the application. Run your test suite, or manually check for the bug you're trying to find.

Step 4: Tell Git What You Found

After you've tested, tell Git whether the bug exists in this new commit.

• If the bug is still there, mark the commit as bad:

    git bisect bad
  

• If the bug is not present and the application works correctly, mark it as good:

    git bisect good
  

• If you can't test a commit—for example, if the code doesn't build or a dependency is missing—you can tell Git to skip it:

    git bisect skip
  

Git will then automatically check out a new commit and repeat the process.

Step 5: Find the Culprit

After a few rounds of testing and marking commits as good or bad, Git will narrow down the search to a single commit.

It will then print the magic message:

[commit_hash] is the first bad commit

Congratulations! You've found the exact commit that introduced the bug. Now you can analyze that specific change, understand what went wrong, and fix it.

Step 6: Clean Up

Finally, to exit the bisect session and return to the branch you were on when you started, run:

git bisect reset

This command will take you back to your original branch and leave your working directory in a clean state.

---

Never Get Lost in Commits Again

Before git bisect, finding bugs in a large commit history felt like searching for a needle in a haystack. But with this powerful command, you can efficiently and systematically find the problem, saving you hours of frustrating manual work.

Next time your project breaks, skip the guessing game and let git bisect guide you to the solution.