Git Bisect Tutorial: Locate the Commit That Introduced a Bug
Gitdebuggingregression testingversion controldeveloper workflow

Git Bisect Tutorial: Locate the Commit That Introduced a Bug

FFunction Forge Editorial Team
2026-11-13
7 min read

Learn how to use Git bisect to find a regression’s first bad commit, automate testing, handle skips, and verify the result safely.

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

  1. Choose a known-good commit, release tag, or branch. This is the revision where the behavior still works.
  2. Choose a known-bad revision. This is where the regression can be reproduced.
  3. Start the session from the repository root:
git bisect start
  1. Mark the failing endpoint or commit:
git bisect bad <bad-revision>
  1. 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 bad

If the behavior is absent, mark it good:

git bisect good

Continue until Git identifies the first bad commit. Record the result, then leave bisect mode:

git bisect reset

Use 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.
  • 1 through 124: 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
fi

Make 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.sh

Keep 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 skip

Git 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

CommandPurpose
git bisect startBegin a bisect session.
git bisect start BAD GOODBegin 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 skipExclude a revision that cannot be classified.
git bisect run COMMANDAutomate classification with a command or script.
git bisect visualizeView commits remaining in the search.
git bisect logPrint the decisions made during the session.
git bisect replay FILEReplay a saved bisect log.
git bisect resetEnd 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 125 for 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 log if 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:

  1. Write down the exact regression and its reproduction command.
  2. Verify a known-good and known-bad revision.
  3. Confirm the working tree is clean and the clone contains the required history.
  4. Run the test at least once outside bisect mode.
  5. Decide how build failures and unavailable dependencies will be classified.
  6. Start bisect and save the session log.
  7. Inspect the first bad commit rather than treating it as final proof.
  8. Run the regression test again after the suspected fix or revert.
  9. 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.

Related Topics

#Git#debugging#regression testing#version control#developer workflow
F

Function Forge Editorial Team

Developer Tools Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.