Git Bisect
debt(d7/e3/b3/t5)
Closest to 'only careful code review or runtime testing' (d7). The common mistakes — not resetting after bisect, marking commits incorrectly, lacking a reproducible test — are not caught by any listed tool (git, phpunit, pest) automatically. Git itself won't warn you that you left a detached HEAD state after bisect, or that you poisoned the search with an unrelated failure. Only careful manual review or noticing unexpected repo state at a later point surfaces these issues.
Closest to 'simple parameterised fix' (e3). The quick_fix describes running a small sequence of git commands (git bisect start, mark good/bad, git bisect run). Correcting a mistake like an unclean bisect state or a poisoned search requires restarting the process — a modest but contained effort within one workflow, not spanning multiple files or components.
Closest to 'localised tax' (b3). Git bisect is a debugging technique invoked episodically; it doesn't impose ongoing structural weight on the codebase. The main burden is ensuring a reproducible test exists and remembering to run git bisect reset, which is a localised procedural tax rather than a codebase-wide commitment.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception field identifies the trap as thinking you need programming history expertise, when in fact you only need a reproducible test. Additional traps include forgetting git bisect reset (leaving detached HEAD), and poisoning the binary search with unrelated failures — documented gotchas that intermediate developers encounter and eventually learn, but not immediately obvious.
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