Git Bisect

Also Known As

TL;DR

Explanation

git bisect automates a binary search through commit history. You mark a known-good commit and a known-bad commit, then git checks out the midpoint. You test and mark it good or bad, halving the search space each time. For 1000 commits, this finds the culprit in ~10 steps. With git bisect run, you automate the test — bisect runs your test suite and marks commits automatically, making regression hunting fully automated.

Diagram

flowchart TD
    START[git bisect start] --> BAD[git bisect bad HEAD<br/>current commit has bug]
    BAD --> GOOD[git bisect good v1.0<br/>this tag was fine]
    GOOD --> MID[Git checks out midpoint]
    MID --> TEST{Test: bug present?}
    TEST -->|yes - git bisect bad| NARROW1[Narrow to upper half]
    TEST -->|no - git bisect good| NARROW2[Narrow to lower half]
    NARROW1 & NARROW2 --> MID
    MID -->|after log2 N steps| FOUND[First bad commit identified]
    FOUND --> RESET[git bisect reset]
    INFO[64 commits = 6 steps<br/>1000 commits = 10 steps]
style FOUND fill:#238636,color:#fff
style INFO fill:#1f6feb,color:#fff

Common Misconception

Why It Matters

Common Mistakes

• Not having a reproducible test before starting bisect — manual marking requires re-testing at each step.
• Marking a commit as bad when it has an unrelated test failure — poisons the search.
• Not running git bisect reset after finishing — leaves the repo in detached HEAD state.
• Not using git bisect run with an automated test — missing the most powerful feature.

Code Examples

# Manual bisect — slow without automation:
git bisect start
git bisect bad HEAD
git bisect good v1.2.0
# Git checks out commit — developer manually runs app and marks
git bisect bad  # or good
# Repeat 10 times manually...

# Automated bisect with test script:
git bisect start
git bisect bad HEAD
git bisect good v1.2.0

# test.sh exits 0 = good, non-zero = bad:
git bisect run ./test.sh
# Git runs binary search automatically — finds the commit
git bisect reset  # Return to original HEAD

References

• ↗ https://git-scm.com/docs/git-bisect

Tags

Related Terms