Debugging issues in a complex codebase can often feel like searching for a needle in a haystack, especially when you’re unsure when a certain bug was introduced. Thankfully, Git has a built-in tool that can help: git bisect.

In this article, I’ll walk you through what git bisect is, how it works, and some tips for making the most out of this powerful feature so you can efficiently locate problematic commits in your project’s history.

What is Git Bisect?

Git Bisect is a command that uses binary search to find the specific commit that introduced a bug or regression. It automates the process of checking out various points in your project’s history to quickly narrow down the offending change. If you know that your code was working at one commit ("good") and broken at another ("bad"), Git Bisect can help you find the culprit in log₂(N) steps, where N is the number of commits in the range.

How to Use Git Bisect

Let’s take a look at a typical workflow to use git bisect:

1. Start the Bisect Session

   git bisect start
   

2. Mark the Bad Commit
   Usually, this is your current commit, where the bug is present.

   git bisect bad
   

3. Mark the Good Commit
   Provide a commit hash where you know the bug did not exist.

   git bisect good <commit_hash>
   

4. Test and Mark Commits
   Git will check out a commit in the middle of the range. Test your code. If the bug is present:

   git bisect bad
   

   If not:

   git bisect good
   

   Repeat this process. Git will keep moving you closer to the problem commit.

5. Finish the Bisect
   When the first bad commit is found, end the bisect session:

   git bisect reset
   

Pro Tips for Efficient Bisecting

• Automate with Scripts: If you can automate the test (e.g., with a test script), Git can run it for you. For example:

  git bisect run ./test-for-my-bug.sh
  

  This will automatically mark commits as good/bad based on your script’s exit status.

• Keep Your Tests Focused: Bisect is most effective when your test exactly captures the bug you’re hunting down. Make sure you can reliably reproduce the problem for each commit.

• Bisecting with Uncommitted Changes: Stash or commit any current changes before starting a bisect to avoid conflicts.

• Restore Your Branch: After you finish bisecting, don’t forget to use git bisect reset to return to your previous HEAD.

Conclusion

git bisect is a huge timesaver for any developer dealing with bugs, regressions, or mysterious changes. Mastering this tool can turn investigating project history from a daunting task into a quick, logical process. Next time you’re staring down a bug and aren’t sure where it crept in, reach for git bisect—it might just save you hours.

Happy debugging!

— Joe Git