October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsPC HealthRecommendedCrashes, freezes, slowdowns? Check your PC nowSpot repairable issues before they interrupt work.Check PCOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
World desk4 min

Twelve Commits, One Regression, Four Test Runs: How to Use `git bisect run`

Use `git bisect run` to automate a binary search for a regression, with practical guidance on endpoints, test exit codes, skipped commits, and the four-run estimate.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

git bisect run can automate the search for a commit that introduced a regression by running a test at successive revisions and using each result to narrow the range. Four runs can be enough in an idealized search across roughly twelve candidates, but Git does not guarantee that count: it depends on the history, the endpoints, and whether every revision can be tested.

What `git bisect run` does

Git bisect performs a binary search between a revision known to be good and one known to be bad. With git bisect run, Git checks out candidate revisions and runs your command at each one. The command’s exit status tells Git how to classify that revision, allowing it to choose the next candidate.

As an Amazon Associate I earn from qualifying purchases.

The result is only as reliable as the two endpoint classifications and the test. The test must measure the same suspected behavior at each revision; a test that is inconsistent across versions or produces flaky results can lead to an unreliable classification. See the Git bisect documentation for the command’s rules and examples.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Can it find the regression in four test runs?

Possibly, but four is an idealized estimate, not a fixed execution count. Each good-or-bad result divides the remaining candidate range. Four binary decisions can distinguish among up to sixteen equally selectable possibilities, so four runs can be enough when searching a range of about twelve candidate revisions.

The phrase “twelve commits” needs a precise meaning. If the two known endpoints are included in the twelve, fewer than twelve commits remain as possible culprits. If twelve means twelve candidate revisions between known endpoints, that is a different search range. Git’s documentation describes approximate step counts rather than promising exactly four test executions for every twelve-commit history.

History shape and testability also matter. Uneven histories, merges, and revisions that must be skipped can change the number of useful decisions. A skipped commit near the boundary may leave Git unable to name one unique first bad commit.

Set known-good and known-bad endpoints

Choose a revision where the test passes and one where it fails, then make that range explicit. The Git documentation demonstrates this command:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
git bisect start HEAD HEAD~10 --

In this example, HEAD is treated as bad and HEAD~10 as good. These are illustrative endpoints, not defaults to copy blindly; replace them with revisions that actually bracket the regression in your repository.

Write a test command that classifies each revision

For git bisect run, the exit status has a specific meaning:

  • 0: the revision is good (the old behavior).
  • 1 through 127, except 125: the revision is bad (the new behavior).
  • 125: the revision cannot be tested, so Git should skip it.
  • Any other status: the bisect run aborts.

A test script should return 0 when the suspected regression is absent and a bad status when it is present. If a revision cannot build for an unrelated reason, returning 125 prevents that build failure from being mistaken for the regression. The documented example uses:

#!/bin/sh
make || exit 125
~/check_test_case.sh

Here, a failed build makes the revision untestable, while the checker supplies the good-or-bad result. Use 125 only when the selected revision cannot be tested—not as a general way to report a failing test. When practical, keep the scripts outside the repository to avoid interactions among the bisect, build, and test processes.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Run the automated search

  1. Start the bisect with the known bad and good endpoints, as in git bisect start HEAD HEAD~10 --, after adapting the revisions to your regression window.
  2. Run your test script with git bisect run ~/test.sh. Git will check out candidates and use the script’s exit status to narrow the range.
  3. Read Git’s result in light of any skipped revisions. If a skipped commit is adjacent to the suspected change, the output may identify a boundary or narrowed region rather than a uniquely proven culprit.

To compare approaches: manual bisecting lets you inspect each revision and decide how to classify it, while git bisect run is suited to a repeatable, machine-checkable test. Automation is not a substitute for a usable test: revisions that cannot be tested need explicit handling, and an unstable test weakens the result.

Handle skipped commits and verify the result

When Git skips an untestable revision, it may be unable to determine exactly which adjacent commit was first bad. Treat that result as a narrowed region, not as proof of one culprit. If possible, test neighboring commits manually or improve the script or environment so those revisions can be classified.

Even with no skipped revisions, confirm that the candidate reproduces the failure and that the preceding revision does not. The bisect classification relies on the endpoints and on the test applying consistently across the history; a flaky test or one that depends on changing external services can undermine that assumption.

Reset after the search

When you are finished, run:

git bisect reset

By default, this returns the checkout to the commit that was active before git bisect start. You can supply a different target commit to git bisect reset if you want to return elsewhere.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
Crashes, No Sound, or Screen Glitches?Free driver scan
Windows Errors? Fix Them Before They SpreadFree repair scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.