Git Bisect: Find a Regression Commit with Repeatable Tests

A feature worked in the previous release but fails now, with dozens of commits between them. Git bisect narrows the search by testing intermediate revisions instead of guessing which change looks suspicious.

Use a dedicated test copy of the repository. Release names below are placeholders. Do not switch revisions in a production-serving directory or one containing unsaved work.

1. Define a repeatable failure

Document the input, action, expected result and actual result. “Sometimes slow” is not a strong classifier; a small reproducible test makes each decision more reliable.

Use consistent fixtures, record runtime versions, disable unrelated background tasks and avoid real email or payment effects. Repeat the test at both endpoints to detect instability before starting.

2. Identify known good and bad endpoints

Pro Git describes narrowing history through good/bad results. Choose an older revision verified not to exhibit the failure and a newer one that does. A successful deployment is not proof that this particular test passed.

git status --short
git bisect start
git bisect bad release-broken
git bisect good release-working

Replace both release names with verified tags or hashes, with good preceding the failure in the relevant history. Stop and preserve outstanding changes if status is not clean; do not use a hard reset for convenient cleanup.

3. Test the selected revision

Git selects an intermediate commit. Prepare its environment, run the reproduction and choose only the applicable command:

git bisect good
# OR
git bisect bad
# OR, when this revision cannot be tested:
git bisect skip

The git-bisect manual provides skip for untestable revisions; skipped candidates can prevent identifying one exact culprit. An unavailable historical dependency is not automatically the regression being investigated.

Record the hash, outcome and reason for skips. If the failure appeared, disappeared and returned, narrow the period first rather than assuming a single clean behavioral boundary.

4. Automate only after stabilizing the test

git bisect run classifies exit 0 as good; 1–127 except 125 as bad; 125 as skip; other codes stop the process. A missing test command can therefore look like a product failure unless the wrapper distinguishes causes.

git bisect run /absolute/path/to/check-regression.sh

This path stands for a project-specific script, not a supplied file. Keep the checker outside the changing source tree if necessary, and ensure compatibility with older revisions. Separate environmental failure from the targeted regression, but do not blindly convert every error to skip.

5. Confirm the result and end the session

Review the candidate diff and rerun the test at that commit and an appropriate preceding revision. For merges, examine parents and integration context instead of assuming the first parent explains everything.

git show --stat
git show
git bisect log
git bisect reset

Record the log before resetting. The final command ends bisection and normally restores the starting HEAD; it cannot undo database or external-service changes made by tests.

6. Reliability checklist

• Both endpoints use the same behavioral criterion.
• Tests avoid uncontrolled time, network and changing data.
• Dependencies and configuration match each revision.
• Environment failures are not mislabeled regressions.
• The candidate is confirmed before fixing or reverting.
• The eventual fix includes a regression test.

Bisect locates a behavioral transition, not its full root cause. Its value depends on a clear reproduction and consistent evidence.