Git Bisect: Finding the Commit That Broke Your Code

A bug appears in your application, but you have no idea which commit introduced it. You could read through hundreds of commits manually, or you could let Git do a binary search for you. git bisect checks out commits one by one, narrowing the range until it finds the exact commit where the behavior changed.

How Bisect Works

Bisect performs a binary search between a known-good commit and a known-bad commit. At each step, Git checks out the middle commit, you test whether the bug is present, and Git narrows the range. For 1000 commits, this takes about 10 steps instead of reading 1000 commit messages.

Step-by-Step Process

1. Start Bisect

git bisect start

2. Mark the Current Commit as Bad

This is the commit where you know the bug exists:

git bisect bad

3. Mark a Known Good Commit

Point Git to a commit where the bug did not exist. You can use a tag, a branch, or a commit hash:

git bisect good v2.0.25

Git now checks out the midpoint between the good and bad commits.

4. Test the Current Commit

Build and test the code at the checked-out commit. Run the specific test case or manually verify the behavior.

5. Tell Git the Result

# If the bug is present at this commit:
git bisect bad

# If the bug is NOT present at this commit:
git bisect good

Git narrows the range and checks out the next midpoint. Repeat steps 4-5 until Git identifies the first bad commit.

6. Return to Your Original Branch

When bisect finishes, it will print the offending commit. Return to your working branch:

git bisect reset

Practical Example

# Start bisect
git bisect start

# Current version has the bug
git bisect bad

# Version 2.0.25 was working correctly
git bisect good v2.0.25

# Git checks out a midpoint. Test it, then:
git bisect good   # or git bisect bad

# Continue until Git finds the first bad commit
# Output: [hash] is the first bad commit

# Return to your branch
git bisect reset

Automated Bisect

If you have a test script that can detect the bug, you can automate the process entirely:

git bisect start HEAD v2.0.25
git bisect run ./test-script.sh

Git will run the script at each midpoint and automatically mark commits as good or bad based on the exit code (0 = good, non-zero = bad).

Useful Commands During Bisect

# See the current range of commits being tested
git bisect log

# Visualize the bisect progress
git bisect visualize

# Skip a commit that cannot be tested (build failure, etc.)
git bisect skip

Common Mistakes

A.M. Rinas

Written by A.M. Rinas

Full-Stack Software Engineer working on web applications, DevOps automation, and databases. More about me on the about page, or say hi through the contact page and LinkedIn.

← Back to all articles