Finding a Bug with Bisect

Binary search through history

Something worked before and doesn’t now. If you know where to look, git log -p and git blame (module 2) will find it. If you don’t, and there are dozens of commits between “worked” and “broken,” git bisect finds the guilty commit for you ¹.

It does a binary search. You tell it one commit that’s bad and one older commit that was good. Git checks out the commit halfway between, and you test it: if it’s good, the problem came later, and if it’s bad, it came earlier or right there. Either way, half the suspects are ruled out ¹. Twelve commits take about four tests; a thousand take about ten, because 2 to the 10th is 1,024.

Bisecting by hand

The garden repository’s beds.txt has lost its garlic somewhere in the last twelve commits:

me@linuxbox:~/garden$ git log --oneline
a808cbe Add a second bean row
8b7d6df Add carrots
d5efca9 Add lettuce
84a5c2a Add peppers
af196a8 Tidy the bed list
0f62044 Add basil
2d9ae6c Add marigolds
23aad32 Add tomatoes
1b2c175 Add squash
f9144a6 Add garlic
dc1726b Add beans
dbb729a Plan the beds
me@linuxbox:~/garden$ grep garlic beds.txt
me@linuxbox:~/garden$

Start, mark the current commit bad, and mark a commit you know was good; here, the first one ²:

me@linuxbox:~/garden$ git bisect start
status: waiting for both 'good' and 'bad' commits
me@linuxbox:~/garden$ git bisect bad
status: waiting for 'good' commit(s), 'bad' commit known
me@linuxbox:~/garden$ git bisect good dbb729a
Bisecting: 5 revisions left to test after this (roughly 3 steps)
[2d9ae6c0b9fe3ef4fb5969b44bc25bc4e9a9697c] Add marigolds

Git has checked out Add marigolds, halfway along. Test it, and say what you found:

me@linuxbox:~/garden$ grep garlic beds.txt
garlic
me@linuxbox:~/garden$ git bisect good
Bisecting: 2 revisions left to test after this (roughly 2 steps)
[84a5c2a5184ca8a9c7bedddea0a4a948dc9d4eca] Add peppers
me@linuxbox:~/garden$ grep garlic beds.txt
me@linuxbox:~/garden$ git bisect bad
Bisecting: 0 revisions left to test after this (roughly 1 step)
[af196a8ff4e3443477e402a39eb4c0811fafec49] Tidy the bed list
me@linuxbox:~/garden$ grep garlic beds.txt
me@linuxbox:~/garden$ git bisect bad
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[0f620447a072b53a10a541ec2f32707d80ee6988] Add basil
me@linuxbox:~/garden$ grep garlic beds.txt
garlic
me@linuxbox:~/garden$ git bisect good
af196a8ff4e3443477e402a39eb4c0811fafec49 is the first 'bad' commit
commit af196a8ff4e3443477e402a39eb4c0811fafec49
Author: Me <me@example.com>
Date:   Mon Oct 5 09:16:00 2026 -0500

    Tidy the bed list

 beds.txt | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

Four tests, and git names the commit: Tidy the bed list, which removed garlic while sorting the list. git show af196a8 shows exactly what it changed.

While bisecting, you’re on old commits in detached HEAD (module 3), so don’t do new work there. When you’re done, git bisect reset puts you back on the branch you started from ¹:

me@linuxbox:~/garden$ git bisect reset
Previous HEAD position was 0f62044 Add basil
Switched to branch 'main'

If a commit can’t be tested, say it’s half-finished and doesn’t run, git bisect skip asks git to pick a nearby one instead. Skip next to the culprit, though, and git can only say it’s one of a few commits ².

Letting a command decide

If a command can tell good from bad, git can run the whole search itself. Give the bad and good commits to start, then hand the test to git bisect run ^{1 2}:

me@linuxbox:~/garden$ git bisect start HEAD dbb729a
Bisecting: 5 revisions left to test after this (roughly 3 steps)
[2d9ae6c0b9fe3ef4fb5969b44bc25bc4e9a9697c] Add marigolds
me@linuxbox:~/garden$ git bisect run grep -q garlic beds.txt
running 'grep' '-q' 'garlic' 'beds.txt'
Bisecting: 2 revisions left to test after this (roughly 2 steps)
[84a5c2a5184ca8a9c7bedddea0a4a948dc9d4eca] Add peppers
running 'grep' '-q' 'garlic' 'beds.txt'
Bisecting: 0 revisions left to test after this (roughly 1 step)
[af196a8ff4e3443477e402a39eb4c0811fafec49] Tidy the bed list
running 'grep' '-q' 'garlic' 'beds.txt'
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[0f620447a072b53a10a541ec2f32707d80ee6988] Add basil
running 'grep' '-q' 'garlic' 'beds.txt'
af196a8ff4e3443477e402a39eb4c0811fafec49 is the first 'bad' commit
...
bisect found first 'bad' commit
me@linuxbox:~/garden$ git bisect reset

Git reads the command’s exit status (Shell course, module 6) ²:

grep -q exits 0 when it finds a match and 1 when it doesn’t, so it works as a test with nothing extra. For real projects the command is usually your test suite, such as make test, or a small script. The git docs’ example skips commits that don’t build ²:

#!/bin/sh
make || exit 125         # can't build: skip this commit
./check_test_case.sh     # exits 0 if the test passes, 1 if not

Keep the test script outside the repository, or untracked, so it doesn’t change as git checks out older commits.

Making bisect work for you

Bisect can only point to a commit, so it’s as precise as your commits are. A small commit that does one thing (module 2) tells you exactly what broke; a giant “lots of changes” commit leaves you searching inside it. That’s one more reason to commit small and often.

Two more commands help with long sessions ²: git bisect log prints the good and bad answers so far, and git bisect visualize (or view) shows the commits still in the running.

Your turn

So

git bisect finds the commit that broke something by binary search: git bisect start, git bisect bad on a broken commit, git bisect good on one that worked, then test and answer good or bad until git names the first bad commit. Each answer halves the suspects, so about ten tests cover a thousand commits. git bisect run <command> automates it, reading exit status 0 as good, 1 to 127 as bad, and 125 as skip. Always finish with git bisect reset.