Git bisect: find the commit that broke your build after an AI agent ran
TL;DR: git bisect run <cmd> automates the whole “which commit broke it” loop, and the only thing you have to get right is the exit code of your check script. Zero means the revision is good, 1 through 127 means it is bad, 125 means “this revision cannot be tested, skip it”, and any other code aborts the search. With an agent that leaves you 20 commits and a failing test suite, that is the difference between an afternoon of reading diffs and one command.
What you’ll be able to do:
- Turn “the build broke after the agent ran” into a single automated search that reports the first bad commit.
- Write a check script whose exit code tells Git good, bad, or skip, so broken intermediate commits do not poison the search.
- Use
--first-parentand--reset-when-foundso a merge commit does not get blamed for a bug an earlier branch introduced.
Honest take: Bisect answers “which commit first made this test fail”, nothing more. If the breakage has two independent causes, or if the failure only appears on your machine and not in the check script, bisect will confidently point at the wrong commit.
Why an AI agent makes bisect necessary
A normal bug arrives with a small diff. You read it, you see the mistake, you fix it. An AI coding session arrives differently: the agent ran for twenty minutes, edited eleven files, and left the branch with 14 commits in a row. The test suite now fails, but the failing line was last touched in commit 9, while commit 14 is the one that happened to trigger the failure.
Reading backwards from the last commit is slow and biased — the most recent diff is the one your eye goes to first, and it is rarely the one that caused the problem. Git bisect does the search properly: it asks you for one commit you know is good and one you know is bad, then it checks out the midpoint of the remaining range, over and over, until only one candidate is left.
The Git manual describes the command as a way to “find which commit in your project’s history introduced a bug”, and notes that it works for any property, not just bugs — the commit that fixed something, or the one that improved a benchmark. The official git-bisect documentation, checked November 15, 2026, is the reference for every option used below.
The exit code is the whole contract
git bisect run does not parse output. It reads the exit status of the command you gave it, and the documented mapping is precise:
| Exit code | Git’s interpretation | What your check script should return it for |
|---|---|---|
0 | The revision is good | The test suite passed on this revision |
1–127 | The revision is bad | The test suite failed, or the failure is clearly this revision’s fault |
125 | The revision is skipped | This revision cannot be tested at all (missing dependency, does not compile, needs a file that is not in this revision) |
126, 127, or anything else | The run is aborted | Never return these from the script — Git treats them as an error in your script, not as a verdict |
The manual is explicit about the skip code: “The special exit code 125 should be used when the current source code cannot be tested. If the script exits with this code, the current revision will be skipped.” It also explains why 125 is the value chosen — 126 and 127 are reserved by POSIX shells for “command found but not executable” and “command not found”, so they are not usable as verdicts.
Two rules follow directly from the table:
- Never let a shell error become your verdict. If your test command is
pytestand pytest is not installed on that revision, the shell returns 127 and Git aborts the whole search instead of skipping that revision. Capture the real result yourself and exit 125 for “could not run”. - Never return 125 for a genuine failure. 125 means “unknown”, and every skip narrows the range less than you might think. If you skip too much, Git tells you it could not narrow the range down.
The manual loop, and the automated one
The manual form is three commands and one judgement per step:
git bisect start # enter bisect mode
git bisect bad # the current checkout is the broken one
git bisect good <known-good-ref> # a ref that worked before
# Git checks out a midpoint; then repeat:
git bisect good # or: git bisect bad
Each round Git tells you how many revisions are left, for example “Bisecting: 675 revisions left to test after this (roughly 10 steps)”. With 14 agent commits, that is four test runs instead of fourteen diff reviews.
The automated form replaces your judgement with a script:
git bisect start HEAD origin/main -- # HEAD is bad, origin/main is good
git bisect run ./check.sh # the script decides good/bad/skip
git bisect reset # leave bisect mode
The manual’s own examples use exactly this shape, including the git bisect start <bad> <good> -- form with a trailing -- to end option parsing, and the git bisect reset at the end to return to the original checkout.
Writing a check script that does not lie
The script is the part people get wrong. A reliable one separates three outcomes — passed, failed, and cannot-be-tested — and it makes sure the shell never decides the verdict for it:
#!/usr/bin/env bash
# check.sh - exit 0 = good, 1 = bad, 125 = skip this revision
set -u
if ! command -v pytest >/dev/null 2>&1; then
echo "pytest not available in this revision - skipping"
exit 125
fi
if ! python -c "import app" >/dev/null 2>&1; then
echo "app package does not import in this revision - skipping"
exit 125
fi
if pytest -q tests/; then
exit 0 # good
else
exit 1 # bad
fi
Three details in that script are load-bearing:
- Missing tooling exits 125, not 127.
command -vturns “not installed” into an explicit skip instead of letting the shell produce an abort code. - An import failure is a skip, not a bad verdict. If the package does not even import on this revision, the test suite cannot express the bug, and marking the revision bad would blame a commit that merely has a different module layout.
- Only the final test run produces a verdict. Everything before it decides whether the test can run at all.
If your agent commits are large and your suite is slow, a faster check script is worth writing: a single unit test that reproduces the bug is often enough, and git bisect run will happily run a one-line script.
Options that matter when agents merge branches
Agents frequently work on branches and merge them. Two documented options keep the search honest in that situation.
--first-parent follows only the first parent when it meets a merge commit. The manual explains why this matters: “In detecting regressions introduced through the merging of a branch, the merge commit will be identified as introduction of the bug and its ancestors will be ignored.” Without it, a merge commit gets blamed for a bug that an earlier branch commit introduced.
--reset-when-found[=<where>] cleans up as soon as the first bad commit is identified. With no argument it returns to the commit you were on when you started; with =found it leaves the first bad commit checked out so you can read the diff immediately.
git bisect start --first-parent HEAD origin/main --
git bisect run --reset-when-found=found ./check.sh
The --no-checkout option is for the case where your check does not need a checked-out tree; Git then only moves the BISECT_HEAD reference. Most people should leave it alone.
How does this fit into an AI review pipeline?
Bisect is the last step of a pipeline, not the first. The other steps decide what to test and keep the diffs small enough to review.
- The Git diff exit-code pipeline guide covers why a review script must never treat a non-zero diff exit as a failure, which is the same discipline bisect demands from a check script.
- The staged and untracked file check catches the files an agent created but never staged, which is exactly the state bisect cannot search.
- The patch path scope check keeps an agent’s patch inside the paths you authorised, so the history you are about to bisect is history you recognise.
Two preconditions are worth stating plainly, because both silently break bisect:
- The work must be committed. Bisect moves
HEADbetween commits. Uncommitted changes are not part of any revision, and the search will not include them. Commit or stash first. - The history must be linear enough to search. If the agent rewrote history with a rebase or an amend, the “known good” ref you point at may no longer exist. Check
git log --onelinebefore you start.
How can you validate the bisect contract locally?
The behaviour above was reproduced on this machine with Git 2.47.3 and a purpose-built fixture repository: a linear history of twelve commits, each touching one file, with a single commit that introduces the failure, plus one commit that cannot be tested at all so the skip path is exercised too.
| Fixture case | Setup | Observed result | What it proves |
|---|---|---|---|
| One bad commit inside the searched range | 12 commits, the break starts at commit 6 and stays broken after it | git bisect run names commit 6 as the first bad commit | The 0/1 exit-code contract drives the search correctly |
| Revision that cannot be tested | Every commit from 7 on makes check.sh exit 125 | The untestable revisions are skipped, the search continues, and commit 6 is still identified | The skip code prevents a false “bad” verdict |
| Check script always fails | Script exits 1 on every revision | Bisect reports the earliest candidate in the range | Git uses the exit code, not the script’s output text |
| Check script exits outside 0–127 | Script exits 200 | The run stops with error: bisect run failed: exit code 200 from './check.sh' is < 0 or >= 128 | An aborted run is safer than a wrong commit |
| Empty range | Good and bad refs point at the same commit | Git reports that the same commit was both good and bad | A wrong starting point is caught early, not guessed at |
These are the documented Git behaviours exercised against a local fixture. They are not a measurement of how long a bisect takes on your repository — that depends on the depth of your history and the runtime of your check script.
Honest take: what bisect cannot tell you
Bisect reports the first commit where your check script fails. That is genuinely useful, and it is also the limit of the claim.
- It finds a commit, not a cause. The commit it names is the first one where your check fails, which is not necessarily the commit that introduced the bug. A check that depends on accumulated state can blame the wrong commit.
- It assumes one culprit. Two independent regressions that both make the test fail will make the search report the first one and stop. Fix it, then run the search again.
- It assumes the breakage is monotonic. The binary search only makes sense if a revision that fails keeps failing in every later revision. A bug that appears and then disappears — a feature flag, a date-dependent test, a dependency upgrade and downgrade — breaks that assumption, and the search can confidently name a commit that was never the culprit. That is why the fixture above breaks the build from one commit onwards and never repairs it.
- It only sees committed work. A bug that exists only in your working tree is invisible to bisect by construction.
- It is only as honest as the script. A check script that returns 0 when it cannot run turns the entire search into a rubber stamp, and Git will happily report the earliest commit in the range as “good”.
Use it when the history is committed, the failure is reproducible by a command, and the agent left more than three commits in a row. Those are the cases where bisect is faster than reading diffs, and where the exit-code contract does the work for you.
Sources
- git-bisect — Git reference documentation
- Bisecting — Pro Git book, branching chapter
- git stash — Git reference documentation
- git log — Git reference documentation
- git revert — Git reference documentation
Last updated November 15, 2026. Official Git documentation and the Pro Git book were checked on this date. Local verification used a purpose-built fixture repository with Git 2.47.3 and shell check scripts, without contacting any hosted service, paid API, or commercial tool.
Was this article helpful?
Thanks for the feedback — it helps improve future articles.
Need hands-on help?
I offer 1-on-1 technical consulting for local AI setup, GPU selection, and AI coding tool configuration — same topics covered on this site.
Book a session — $49 / hour →Know which coding tool is worth paying for
Hands-on comparisons of AI coding assistants and what each one costs to run — including the local-model path. Sent only when something changes. Unsubscribe anytime.