Skip to main content

Git bisect exit code 125: distinguish a broken test from a broken commit

Updated 5 min readMarkdown

A regression search can produce a precise commit hash for the wrong problem. The dangerous step is often not Git's search algorithm; it is the wrapper deciding what “bad” means.

In our five-commit discount demo, the first wrapper blamed commit C. A better probe found D. The price calculation was still correct at C, but a missing test fixture prevented the original check from reaching it.

This companion explains how to separate a failed assertion from a test that could not run, and why an honest skip sometimes leaves more than one candidate.

Watch the three searches

https://www.youtube.com/watch?v=zJNdg9vyecg

The video is Git Bisect Blamed the Wrong Commit. Here's Why. The example below comes from its recorded local demo, not an AI-model benchmark.

One history, two different questions

The program accepts a price in integer cents. For an input of 1000, the expected discounted output is 900.

  • A: establishes the discount; output is 900.
  • B: documents integer cents; output is still 900.
  • C: removes the test fixture, case.json, but does not break the calculation.
  • D: introduces the discount regression and restores the fixture; output becomes 1000.
  • E: updates the README; the regression remains.

The naïve wrapper loads the fixture before launching the price program. At C, loading the missing file fails. The wrapper returns status 1, so Git records C as bad without the price program ever running there. B passes, and the search identifies C as the first bad commit.

That answer is consistent with the wrapper's question: “Did anything in this test procedure fail?” It is not an answer to the intended question: “Did the discount calculation regress?”

The exit-code contract

For git bisect run, the Git manual defines these outcomes:

Probe exit status Meaning to Git
0 This revision is good
125 This revision cannot be tested; skip it
1–127, except 125 This revision is bad
Other status codes Abort the bisect process

In this demo, status 1 deliberately represents a completed check whose actual price differs from the expected price. Status 125 represents an untestable revision.

Do not blindly forward every subprocess failure as a bad result. For example, shell statuses 126 and 127 usually indicate execution problems, yet fall inside Git's bad-result range. Your wrapper needs an explicit policy for setup failures, unavailable dependencies, and genuine reproduction of the target bug.

What skipping C actually proves

In the second run, the same missing fixture returns 125 instead of 1. Git skips C. B passes, and D runs successfully but returns 1000 instead of 900.

The result is not “D is definitely the culprit.” Git reports C or D as possible first bad commits. There is still no measurement at C, which sits beside the first observed failure.

That uncertainty is useful information. Exit code 125 does not repair the revision, prove it correct, or guarantee a unique culprit. It prevents a missing observation from being mislabeled as evidence of the regression.

Make the probe independent where possible

The third run removes an unnecessary dependency on repository history. In this particular demo, the fixture only contains the input and expected result, so the external probe supplies those same values directly: 1000 in, 900 expected.

It still executes the actual price program from each checked-out revision. It does not substitute a modern implementation or inspect the commit label to guess the answer.

Now C produces 900 and passes. D produces 1000 and fails. Git identifies D, and the recorded direct checks across all five revisions confirm the same boundary.

The general lesson is to keep the question stable while the implementation changes. An external test harness can help when historical checkouts lose fixtures or test infrastructure. It must still exercise the behavior you are investigating, and its assumptions must remain valid for those revisions.

  1. Define the regression narrowly. Write down the input, expected behavior, and what observation counts as failure.
  2. Check both endpoints with the same probe. Confirm that the known-good revision passes and the known-bad revision reproduces the target problem.
  3. Test a setup failure on purpose. Confirm that an unavailable fixture does not silently become an assertion failure.
  4. Keep the probe outside the changing checkout when appropriate. Avoid losing the runner itself as Git switches revisions.
  5. Save the evidence. Record revision, input, actual output, expected output, and exit status; keep the bisect log too.
  6. Preserve ambiguous results. If Git returns multiple candidates, report them until additional testing closes the gap.

The same checklist applies when a coding agent runs the investigation. Ask for the check that actually executed at the alleged culprit, not just the final hash.

Source and scope

See the official git bisect documentation for the full exit-code contract and skipped-commit behavior.

The video's recorded demo used Git for Windows 2.53.0.windows.3 and Python 3.12.10. Its three search traces and per-revision checks were used to verify this article. The example isolates one regression in a small linear history; it does not establish that every real-world history has one clean good-to-bad transition.

AI assistance disclosure: This companion article was prepared with AI assistance and checked against the video's script, recorded demo results, and Git documentation.

About the author

  • Fluid Coding & AI shares practical explainers on AI coding tools, coding agents, and local language models. Companion articles provide useful takeaways and links to our YouTube videos: https://www.youtube.com/channel/UC33TW-QudYXRE-zIIh00NKA

No comments yet. Be the first to comment.