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.

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.

See: Basic bisect commands

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.

See: Basic bisect commands

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.

See: Bisect visualize/view

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.

See: Avoiding testing a commit

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

ExitGit treats it as
0good
1–124bad
125skip this commit
126–127abort (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.

See: Bisect log and replay

Replay a log

git bisect reset
git bisect replay bisect.log

Delete a wrong git bisect good or git bisect bad line before replaying.

See: Bisect log and replay

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

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.

See: Cutting down bisection

Also see

0 Comments for this cheatsheet. Write yours!