When a test or feature worked in one release and fails in another, Git bisect can narrow the search to the commit that introduced the regression. This tutorial provides a repeatable workflow for defining good and bad revisions, testing each midpoint, automating the search with git bisect run, handling inconclusive commits, and safely ending the session.
Overview
Git bisect uses a binary search across a commit range. You identify one revision where the behavior is known to work and another where it is known to fail. Git checks out a commit between them, you run a reliable test, and Git uses the result to select the next half of the range. Each decision removes a large portion of the remaining history from consideration.
The workflow is useful for application bugs, broken builds, changed API responses, frontend regressions, and failing automated tests. It works best when:
- You can state a clear pass or fail condition.
- You know at least one good revision and one bad revision.
- The test can be run consistently on a checked-out commit.
- The commits in the search range are reasonably buildable or testable.
Before starting, save local changes, confirm the repository is in a safe state, and write down the exact command or manual check that distinguishes good from bad. If the regression involves a browser test, stabilize the test as much as possible first; the Playwright Test Debugging Guide covers ways to separate genuine failures from flaky runs.
Checklist by scenario
1. Find a regression between two known revisions
- Choose a known-good commit, release tag, or branch. This is the revision where the behavior still works.
- Choose a known-bad revision. This is where the regression can be reproduced.
- Start the session from the repository root:
git bisect start- Mark the failing endpoint or commit:
git bisect bad <bad-revision>- Mark the working endpoint:
git bisect good <good-revision>Git checks out a candidate commit and reports the remaining search range. Run the regression test at that commit. If the behavior is present, mark the commit bad:
git bisect badIf the behavior is absent, mark it good:
git bisect goodContinue until Git identifies the first bad commit. Record the result, then leave bisect mode:
git bisect resetUse git show <commit>, git log -p <commit>^..<commit>, and the affected test or file to inspect what changed. The first bad commit is the earliest commit in the tested range that exhibits the failure; it is not automatically proof that the commit's author or code is solely responsible. A later dependency, environment, or integration change may have exposed the issue.
2. Automate the search with git bisect run
Automation is valuable when the regression can be represented by a stable command. Create a script that returns a status understood by Git:
0: the revision is good.1through124: the revision is bad.125: the revision cannot be tested and should be skipped.
For example, a shell script might look like this:
#!/usr/bin/env bash
set -u
# Install or build only what is required for this revision.
npm ci --ignore-scripts
npm run build
# Replace this with a deterministic regression test.
npm test -- --runInBand test/regression.test.js
status=$?
if [ "$status" -eq 0 ]; then
exit 0
elif [ "$status" -eq 125 ]; then
exit 125
else
exit 1
fiMake the script executable and run it from a bisect session:
chmod +x ./scripts/bisect-regression.sh
git bisect start <bad-revision> <good-revision>
git bisect run ./scripts/bisect-regression.shKeep the script focused. Avoid commands that depend on interactive input, network services that change between runs, current time, random data, or a developer-specific environment. If setup fails because a commit uses an incompatible dependency or build process, return 125 rather than incorrectly labeling the commit good or bad.
3. Handle commits that cannot be tested
Sometimes a midpoint does not build, requires a missing migration, or falls outside the part of the repository relevant to the regression. Mark it as unknown:
git bisect skipGit then searches another candidate. Skipping too many commits reduces confidence and may leave the exact boundary unresolved. If the final result identifies a range rather than a single useful commit, inspect the skipped commits and test them with a corrected setup.
4. Search a monorepo or a particular path
In a monorepo, first decide whether the regression is isolated to one package. Limit the test script to that package and its required dependencies. If the suspected change is easier to identify by history, use path-aware log commands before or after the bisect:
git log --oneline -- path/to/package
git show --stat <first-bad-commit>Do not assume that a commit touching the target directory caused the issue. Shared configuration, generated files, lockfiles, and build tooling can affect a package without changing its own source files.
Command reference
| Command | Purpose |
|---|---|
git bisect start | Begin a bisect session. |
git bisect start BAD GOOD | Begin with known bad and good revisions. |
git bisect good [revision] | Mark a revision as working. |
git bisect bad [revision] | Mark a revision as failing. |
git bisect skip | Exclude a revision that cannot be classified. |
git bisect run COMMAND | Automate classification with a command or script. |
git bisect visualize | View commits remaining in the search. |
git bisect log | Print the decisions made during the session. |
git bisect replay FILE | Replay a saved bisect log. |
git bisect reset | End bisect mode and return to the previous branch or commit. |
What to double-check
- The endpoints: Reproduce the failure at the bad revision and verify the good revision really passes. A wrong endpoint can produce a technically correct but irrelevant result.
- The test oracle: Define what pass and fail mean. For an API regression, check status code and response shape rather than relying only on a vague visual impression. For a build issue, distinguish compiler failure from a failing test.
- The environment: Use the same runtime, operating system assumptions, database state, environment variables, and dependency installation method whenever possible. Containerizing the test can reduce environmental variation; see the Dockerfile Best Practices guide for ways to keep that setup maintainable.
- Generated and external inputs: Check whether generated assets, lockfiles, fixtures, caches, or remote services change the outcome. Regenerate only when the project expects it, and document the step in the script.
- Automation exit codes: Confirm that the script returns zero only for a good revision, a nonzero test failure for a bad revision, and
125for an untestable revision. A shell pipeline may hide the status you intended unless its failure behavior is explicit. - Repository state: Confirm that no unrelated local modifications are being carried between checkouts. Save the bisect transcript with
git bisect logif the investigation may need to be resumed or reviewed.
Common mistakes
Starting with an uncertain good revision
Bisect depends on a valid boundary. If the supposed good revision has the bug under a different test condition, the search result will not answer the question you intended to ask. Reproduce both endpoints before beginning.
Calling every build failure “bad”
A build failure may mean the revision cannot be classified, not that it introduced the target regression. Investigate the failure and use git bisect skip when appropriate. If the build setup changed, make the script adapt to the revision or narrow the search range.
Using a flaky test
A nondeterministic result can send the search in the wrong direction. Run the test repeatedly at the endpoints, remove timing sensitivity where possible, and treat inconsistent candidates as untrusted. If CI is the only reliable environment, reproduce its relevant setup locally or run the bisect in a controlled job; the GitHub Actions Workflow Validator Guide can help when workflow configuration is part of the setup.
Forgetting to reset
During bisect, Git checks out candidate commits that may leave you in a detached HEAD state. Always run git bisect reset when finished. Then verify the branch and working tree before making changes.
Using a shallow clone without enough history
A shallow clone may not contain the good and bad boundaries or the intermediate commits. Fetch the required history, or create a fresh clone with enough depth for the search. If you deepen incrementally, recheck that both endpoint revisions are available before starting.
When to revisit
Use this checklist whenever a release comparison reveals a regression with an unknown cause, a test starts failing after a merge, or a previously working deployment changes behavior. Revisit the automation whenever the project changes its runtime, package manager, test command, build process, monorepo layout, or CI environment. A script that once classified commits correctly can become misleading after those changes.
Before each investigation, run this compact checklist:
- Write down the exact regression and its reproduction command.
- Verify a known-good and known-bad revision.
- Confirm the working tree is clean and the clone contains the required history.
- Run the test at least once outside bisect mode.
- Decide how build failures and unavailable dependencies will be classified.
- Start bisect and save the session log.
- Inspect the first bad commit rather than treating it as final proof.
- Run the regression test again after the suspected fix or revert.
- Reset bisect mode and record the result in the issue or incident notes.
Keeping the test script, environment assumptions, and result together turns Git bisect from a one-off debugging trick into a dependable developer workflow tool.