When a regression appears after dozens or hundreds of commits, git bisect turns a vague search into a controlled experiment. This tutorial gives you a reusable checklist for identifying the first bad commit, automating the search with tests, handling unbuildable revisions, and verifying the result before changing code.
Overview
Git bisect uses binary search. You provide one revision known to work and another known to fail, and Git checks out a midpoint between them. You test that revision, mark it good or bad, and repeat. Each decision removes roughly half of the remaining history from consideration.
The workflow is useful when the bug is reproducible and the relevant history contains a reliable good boundary. It is less suitable for problems caused by external services, nondeterministic timing, changing data, or tests that cannot distinguish a regression from an unrelated failure.
Before starting, record the symptom and make the test repeatable. For example, define what “bad” means: a command exits nonzero, a particular assertion fails, an HTTP response has the wrong status, or a browser test reproduces a visible defect. If the failure is in an API or frontend workflow, first isolate it with a focused test or a small reproduction. An API debugging runbook can help turn a broad client failure into a check that bisect can execute consistently.
Core command reference
| Command | Purpose |
|---|---|
git bisect start | Begin a bisect session. |
git bisect bad [revision] | Mark the current or specified revision as failing. |
git bisect good [revision] | Mark the current or specified revision as working. |
git bisect run <command> | Run a command at each candidate revision and use its exit status. |
git bisect skip | Exclude a revision that cannot be evaluated reliably. |
git bisect visualize | Show remaining candidate revisions in a history viewer. |
git bisect terms | Display the current good and bad terms. |
git bisect reset | End the session and return to the previous branch or starting state. |
Checklist by scenario
Manual bisect for a small or interactive bug
- Save your work. Commit, stash, or otherwise preserve uncommitted changes. Bisect checks out different commits and may conflict with local modifications.
- Choose boundaries. Find a revision where the behavior is definitely broken and one where it is definitely correct. The good revision must be an ancestor of the bad revision for a straightforward search.
- Start the session. From the repository, run:
git bisect start git bisect bad <known-bad-commit> git bisect good <known-good-commit> - Test the checked-out revision. Rebuild or reinstall dependencies if required. Run the smallest reliable reproduction.
- Mark the result. Use
git bisect goodwhen the bug is absent andgit bisect badwhen it is present. - Repeat until Git identifies a commit. Git will report a candidate described as the first bad commit when the search narrows sufficiently.
- Record the evidence. Capture the commit ID, subject, test command, environment, and observed result before resetting.
- Leave bisect mode. Run
git bisect reset, then inspect the suspected change normally.
Automated bisect with git bisect run
Automation is preferable when the regression can be expressed as a deterministic command. The command must return an exit status that Git can interpret: 0 means good, a status from 1 through 127 means bad, and 125 tells Git to skip the revision because it could not be tested. Do not use a script that returns success merely because it completed; it must assert the behavior you care about.
Start with known boundaries, then run a script or test command:
git bisect start
git bisect bad v2.4.0
git bisect good v2.1.0
git bisect run ./scripts/check-regression.shA copy-ready shell template might look like this:
#!/usr/bin/env bash
set -u
# Install or build only what this revision needs.
if ! npm ci --ignore-scripts; then
exit 125
fi
if ! npm test -- --runInBand; then
exit 1
fi
# Replace this with a focused assertion. Exit 0 only when the bug is absent.
node scripts/reproduce-regression.js
status=$?
if [ "$status" -eq 0 ]; then
exit 1 # Reproduction succeeds: this revision is bad.
else
exit 0 # Reproduction fails: this revision is good.
fiAdjust the meaning of the final status to match your test. For a test runner where passing means “the regression is absent,” you can often call the runner directly. For a reproduction script where passing means “the bug occurs,” invert the result as shown. Keep setup failures separate: a missing dependency or compilation failure is usually a reason to return 125, not to label the commit bad.
When a revision cannot build
Older commits may use incompatible dependencies, generated files, or build instructions that no longer work. First decide whether the failure is a genuine product regression or only an evaluation problem. If you cannot establish the answer, skip the revision:
git bisect skipGit may identify a range rather than one definitive commit if skipped revisions prevent a unique answer. At that point, test nearby commits manually, improve the setup script, or choose wider boundaries with a reproducible environment.
What to double-check
- The symptom is stable. Run the check more than once at a known-good and known-bad boundary. A flaky test can send the search in the wrong direction.
- Dependencies are controlled. Lockfiles, runtime versions, environment variables, feature flags, database fixtures, and browser versions can all affect the result.
- The boundaries are valid. If the “good” revision already fails or the “bad” revision passes intermittently, stop and establish stronger evidence.
- Tests are scoped correctly. A full suite may fail for unrelated reasons. A focused regression test is easier to interpret and faster to run.
- Generated and untracked files are handled. Build artifacts or local configuration can make every checkout appear identical or can introduce behavior that is not in the commit history.
- The result is verified. Inspect the candidate with
git show <commit>, reproduce the failure at its parent, and confirm the fix by testing the candidate or a later revision.
For frontend regressions, isolate whether the change affects JavaScript execution, layout, network behavior, or browser storage before bisecting. A focused Browser DevTools performance workflow can help separate a real code regression from a slow environment or an unrelated rendering issue.
Common mistakes
- Starting with only a bad commit. Bisect needs a known-good boundary. If you do not have one, search older releases or commits until the behavior is demonstrably correct.
- Marking every failure as bad. Compilation errors, missing services, and test infrastructure failures should normally be investigated or skipped rather than treated as product failures.
- Leaving local changes in place. Uncommitted edits can affect every candidate. Reset or stash them before beginning.
- Using a flaky reproduction. Random results destroy the assumptions of binary search. Add retries only when they clarify a known transient condition; otherwise fix the test first.
- Forgetting to reset. After the search,
git bisect resetreturns you to the prior checkout. Without it, later commands may run on the candidate commit unexpectedly. - Assuming the commit is the complete explanation. The first bad commit identifies where the observable behavior changed, not necessarily the only contributing change. Review its parent, related files, tests, and subsequent commits.
Recovery checklist
If the session becomes confusing, use this sequence:
- Run
git bisect statusto see the current boundaries and skipped revisions. - Run
git bisect logto review the decisions already made. - Use
git bisect resetto abort safely. - Clean or restore the working tree, then recreate a reliable test.
- Start again with explicit revision names and documented expected results.
When to revisit
Revisit this workflow whenever a release exposes a regression, a previously flaky test becomes reproducible, or a production fix needs to be traced through a long history. Also review automated bisect scripts when the project changes its package manager, test runner, build process, runtime versions, or CI environment. A script that once returned meaningful exit codes can become misleading after such changes.
Before each investigation, run the test at both known boundaries, confirm that setup failures return 125 when appropriate, and check that the working tree is clean. After the investigation, save the bisect log and candidate commit with the bug report. Then verify the suspected change independently and add a regression test if one does not already exist. This turns a one-time debugging session into a repeatable safeguard for the next release.