When you discover a bug that wasn’t there before, the question is: which commit introduced it?

Git bisect helps you find the exact commit that broke your code using a binary search algorithm.

The Problem

You’re working on a project with hundreds of commits. Something that used to work is now broken. You need to find when it broke so you can:

• Understand what change caused the issue
• Know who to ask about the change
• Figure out the proper fix

The Manual Approach

You could manually check out commits one by one:

git checkout <COMMIT_SHA>

Test if the bug exists. If yes, try an older commit. If no, try a newer one. Eventually you’ll narrow it down.

But this is tedious and slow, especially with many commits.

Using Git Bisect

Git bisect automates this binary search process.

Step 1: Start Bisecting

git bisect start

Step 2: Mark the Bad Commit

Tell Git which commit has the bug (usually the current one):

git bisect bad HEAD

Step 3: Mark a Good Commit

Tell Git a commit where the code worked:

git bisect good 7f4d976e7540e28c6b0

Step 4: Let Git Guide You

Git calculates the midpoint and checks it out:

Bisecting: 3 revisions left to test after this (roughly 2 steps)
[d18ebf1c7db9a9b44e8facc5ddb3551e641a64e2] fixes #25

Now test your code. Does the bug exist?

• If yes: git bisect bad
• If no: git bisect good

Git then picks the next commit to test, cutting the remaining commits in half each time.

Step 5: Find the Culprit

After a few iterations (log₂ of your commit count), Git identifies the exact commit that introduced the bug.

Step 6: Return to Normal

When finished, return to your branch:

git bisect reset

Example Session

$ git bisect start
$ git bisect bad HEAD
$ git bisect good abc123

Bisecting: 6 revisions left to test after this (roughly 3 steps)
[def456] Added caching

# Test the code... bug exists
$ git bisect bad

Bisecting: 2 revisions left to test after this (roughly 2 steps)
[ghi789] Refactored database queries

# Test the code... bug doesn't exist
$ git bisect good

Bisecting: 0 revisions left to test after this (roughly 1 step)
[jkl012] Changed timeout value

# Test the code... bug exists!
$ git bisect bad

jkl012 is the first bad commit
commit jkl012
Author: Someone <someone@example.com>
Date:   Mon Jan 15 10:30:00 2024

    Changed timeout value

$ git bisect reset

Automated Bisecting

If you have a test script that returns 0 for success and non-zero for failure:

git bisect start HEAD abc123
git bisect run ./test-script.sh

Git will automatically run your script at each step and find the bad commit without manual intervention.

Tips

• Choose a good commit that you’re confident was working
• The more distant your good and bad commits, the more steps you’ll need
• Works great with automated tests
• Essential for debugging regressions in long-running projects

Lessons in this unit:

0:	Introduction
1:	Working with Remotes
2:	Squashing Commits
3:	Rebase vs Merge
4:	▶︎ Git Bisect for Debugging
5:	Git Worktrees
6:	Git Submodules
7:	Understanding Detached HEAD
8:	Managing Secrets in Git
9:	Git Workflows and Best Practices
10:	How to push to 2 repositories at the same time and keep them in sync
11:	How to update a Git branch from another branch
12:	Git, detached HEAD
13:	Trigger deploys on Netlify with submodules
14:	A Git Cheat Sheet
15:	Git, squashing vs not squashing
16:	An incomplete list of great Git tutorials
17:	Git, what if you forgot to add a file to a commit?
18:	Git workflow to manage work on multiple branches
19:	How to setup the Git SSH keys