Starting a session
Introduction
git bisect binary-searches history for a commit that introduced a bug, testing each midpoint between good and bad endpoints before reset.
- git-bisect manual (git-scm.com)
- Pro Git: Debugging with Git (git-scm.com)
- git-bisect examples (git-scm.com)
Step 1: Mark the endpoints
Interactively
git bisect start
git bisect bad # HEAD fails
git bisect good v1.2.0 # last known good tag
In one command
git bisect start HEAD v1.2.0
Output
Bisecting: 3 revisions left to test after this (roughly 2 steps)
[d093306e4c74e27178f4332bc119b125a541d286] step 4 (broken)
The bracketed commit is checked out; test and mark it.
Step 2: Test and mark
Test
make test # placeholder: your project's test command
Mark
git bisect good # current commit works
git bisect bad # current commit fails
Result
d093306e4c74e27178f4332bc119b125a541d286 is the first 'bad' commit
refs/bisect/bad points at that commit until the session is reset.
Step 3: Rename the outcomes
git bisect start --term-good=passing --term-bad=failing HEAD HEAD~7
git bisect terms
Output
Your current terms are 'passing' for the old state
and 'failing' for the new state.
Mark commits with git bisect passing and git bisect failing instead.
See: Alternate terms
Narrowing the range
Skip what you cannot test
git bisect skip # current commit cannot be tested
git bisect skip HEAD~2..HEAD~1 # range of commits
skip covers commits that fail for unrelated reasons, such as a broken build. If every remaining commit is skipped, Git lists candidates.
See: Bisect skip
Visualize remaining commits
Terminal
git bisect visualize --oneline
Output
d778145 step 8 (broken)
e3d3902 step 7 (broken)
d27c8f4 step 6 (broken)
1d61b4c step 5 (broken)
d093306 step 4 (broken)
941212d step 3 (ok)
c835f75 step 2 (ok)
Desktop
git bisect view --stat
view is an alias. Both open gitk when a display exists, else git log.
Try a nearby commit
git bisect good
git reset --hard HEAD~3
# compile and test the new checkout
git bisect bad
When the suggested commit is unhelpful, the final mark still applies to the checked-out commit.
Automating the search
Run a test script
git bisect run ./check.sh
Output
running './check.sh'
Bisecting: 0 revisions left to test after this (roughly 1 step)
[941212d998fb435277ab5ebf955092f2d7d3af95] step 3 (ok)
running './check.sh'
d093306e4c74e27178f4332bc119b125a541d286 is the first 'bad' commit
bisect found first 'bad' commit
Git runs the script on each candidate and uses its exit status as the mark.
See: Bisect run
Exit codes
| Exit | Git treats it as |
|---|---|
0 | good |
1–124 | bad |
125 | skip this commit |
126–127 | abort (bogus exit code) |
128+ | abort the run |
See: Bisect run
Saving and resuming
Save the log
git bisect log > bisect.log
Log
# bad: [d778145b4e9053434911b243e65b796603f12480] step 8 (broken)
# good: [2319d13da6615005584f096d817ea027afb6e0ee] step 1 (ok)
git bisect start 'HEAD' 'HEAD~7'
git bisect bad d093306e4c74e27178f4332bc119b125a541d286
git bisect good 941212d998fb435277ab5ebf955092f2d7d3af95
Each mark is recorded as a command, so the log can be edited and replayed.
Replay a log
git bisect reset
git bisect replay bisect.log
Delete a wrong git bisect good or git bisect bad line before replaying.
Reset the session
git bisect reset
git bisect reset bisect/bad
git bisect reset HEAD
Output
Previous HEAD position was 941212d step 3 (ok)
Switched to branch 'main'
Plain reset returns to the starting commit; bisect/bad leaves the bad commit checked out. Either clears the session.
See: Bisect reset
Session options
Avoid checkouts
git bisect start --no-checkout HEAD HEAD~7
Git records marks without rewriting files, for builds that manage their own working tree.
See: Options
Narrow the search
First parent
git bisect start --first-parent HEAD HEAD~7
Paths
git bisect start HEAD HEAD~7 -- src/parser
--first-parent ignores merged side branches; a pathspec considers only commits that touch those paths.
0 Comments for this cheatsheet. Write yours!