Debugging can be frustrating, especially when a bug appears in a large codebase and you have no idea when it was introduced. Instead of manually sifting through commits, Git Bisect can help you track down the exact commit that introduced the bug efficiently. In this blog, we’ll explore how Git Bisect works, walk through a practical example, and provide useful tips to make debugging smoother.

What is Git Bisect?

It is a built-in Git tool that helps you perform a binary search through your commit history to find the exact commit that introduced a bug. Instead of checking each commit one by one, it narrows down the search range quickly by repeatedly dividing the history in half.

This makes Git Bisect extremely powerful, especially in large repositories where manually checking each commit would be time-consuming.

How Does It Work?

The process is simple:

1. You start a bisect session.
2. Mark a known good commit where the bug is absent.
3. Mark a bad commit where the bug is present.
4. Git automatically checks out a commit between those two.
5. You test the code at that commit and mark it as either “good” or “bad.”
6. Git continues this process, narrowing the search until it finds the exact problematic commit.

This approach significantly reduces the number of commits you need to check manually.

Step-by-Step Guide to Using It

Imagine you’re working on a project and notice a feature is broken, but you’re not sure when the bug was introduced.

1. Start the Git Bisect Session

$ git bisect start

This command initiates a Git Bisect session, putting Git in bisect mode.

2. Mark a “Good” and “Bad” Commit

You need to tell Git where the bug exists and where it doesn’t.

• Identify a commit where the bug exists and mark it as bad:

$ git bisect bad

• Find a commit where the bug didn’t exist and mark it as good:

$ git bisect good <commit-hash>

Git will now start checking commits between these two points.

3. Git Picks a Commit for You to Test

Git automatically checks out a commit in the middle of the range. Now, test your code to see if the bug is present.

• If the bug is present, mark it as bad:

$ git bisect bad

• If the bug is not present, mark it as good:

$ git bisect good

Each time you mark a commit as good or bad, Git Bisect picks another commit in between to test.

4. Repeat Until the Problematic Commit is Found

Git will continue selecting commits until it pinpoints the exact commit that introduced the bug. Once identified, Git will display the commit hash and message of the problematic commit.

// something like this

<commit-hash> is the first bad commit  

5. End the Bisect Session

Once you’ve found the bad commit, exit bisect mode:

$ git bisect reset

This restores your repository to its original state before the bisect process.

Automating with a Script

If testing the bug manually is tedious, you can automate the process using a script. Here’s how:

$ git bisect start
$ git bisect bad
$ git bisect good <commit-hash>
$ git bisect run ./test-script.sh

Replace ./test-script.sh with your actual test script that returns 0 for good commits and 1 for bad commits. Git Bisect will run the script automatically and stop when the bad commit is found.

Best Practices

• Choose accurate good/bad commits: Ensure your “good” commit is actually bug-free to avoid misleading results.
• Use automation when possible: Automating the testing process speeds up bisecting significantly.
• Document findings: Keep notes on what you find to avoid redoing the process later.
• Reset after bisecting: Always run git bisect reset to return to the original branch.

Why Use Git Bisect?

• Saves time: Finds the problematic commit quickly using a binary search.
• Works with any Git project: No additional tools or setup required.
• Automatable: Can integrate with test scripts to remove manual testing effort.
• Accurate: Pinpoints the exact commit that introduced a bug, reducing debugging guesswork.

Conclusion

Git Bisect is an essential tool for any developer who wants to debug efficiently. By leveraging binary search, it drastically cuts down the time spent hunting for a bug in large codebases. Whether you’re using it manually or automating the process, it’s a powerful addition to your Git workflow.

Next time you’re stuck debugging a mysterious issue, give Git Bisect a try — it’ll make you look like a pro..!