Git Bisect Guide: Find the Commit That Introduced a Bug
GitDebuggingTestingVersion ControlDeveloper Workflow

Git Bisect Guide: Find the Commit That Introduced a Bug

TThe Coding Club Editorial Team
2026-11-19
7 min read

Use Git bisect to trace a regression through commit history, automate tests, handle skips and merges, and verify the first bad commit.

When a regression appears somewhere in a long commit history, git bisect turns a vague search into a controlled binary search. This Git bisect guide explains how to choose reliable good and bad revisions, run a manual or automated investigation, handle merges and untestable commits, and record the final diagnosis without losing your work.

Overview

Git bisect helps answer a focused question: which commit changed the project from working to broken? You provide one known-good revision and one known-bad revision. Git checks out a commit between them, and you classify that revision as good or bad. Each classification removes roughly half of the remaining history until Git identifies the first bad commit.

The method works best when the defect is a regression with a reproducible test. For example, a request that succeeded before a deployment now returns an error, a page that rendered correctly now has a layout failure, or a test that once passed now fails. It is less useful when the failure is intermittent, depends on external state, or was present from the beginning of the project.

Before starting, save unrelated changes, note the exact failure, and decide how you will test each revision. A clean working tree is strongly preferable because bisect checks out different commits and may conflict with local edits.

Core command reference

CommandPurpose
git bisect startBegin a bisect session.
git bisect bad <revision>Mark a revision where the problem exists.
git bisect good <revision>Mark a revision known to work.
git bisect statusShow the current session state and remaining terms.
git bisect logPrint the classifications made during the session.
git bisect skipExclude a revision that cannot be tested reliably.
git bisect run <command>Automate classification with a script or test command.
git bisect resetExit the session and return to the previous branch or starting revision.

Checklist by scenario

Manual investigation

  1. Describe the test. Write down the command, input, expected result, and actual result. Keep the test the same at every revision.
  2. Choose a known-good commit. Select the newest revision where the behavior definitely worked, rather than an old commit chosen only because it is convenient.
  3. Choose a known-bad commit. Use the current failing revision or a release commit where the regression is confirmed.
  4. Start the session. Run git bisect start, then classify the endpoints:
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>

Git checks out a midpoint. Run the reproduction or test, then classify the result:

git bisect good   # the behavior works here
git bisect bad    # the regression is present here

Continue until Git reports the first bad commit. Read that commit carefully, inspect its diff, and verify the result by testing its parent and the commit itself when practical. Finish with:

git bisect reset

Automated tests with git bisect run

Automation is useful when a command can return a dependable exit status. Git interprets exit code 0 as good and a nonzero status from 1 through 127, excluding the special skip status, as bad. A command that returns 125 tells Git that the current revision cannot be tested and should be skipped.

For a simple test, run:

git bisect start HEAD <known-good-commit>
git bisect run ./scripts/reproduce-regression.sh

A small script is safer than a long shell expression because it can prepare dependencies, isolate temporary files, and make the pass/fail rule explicit:

#!/usr/bin/env sh
set -eu

if ./scripts/build-test-fixture.sh; then
  ./bin/check-regression
else
  exit 125
fi

Make the script executable with chmod +x ./scripts/reproduce-regression.sh. The script should avoid changing tracked files, relying on network services, or interpreting an infrastructure failure as a product failure. If a test fails because a dependency cannot be installed, return 125 or fix the environment before rerunning the bisect.

Monorepos and targeted regressions

In a monorepo, test only the affected package when that is technically valid. Use the repository's established workspace, build, or test command, and make sure the command still exists at older commits. If package boundaries changed during the search, a targeted command may produce misleading results; use a stable integration test instead.

For a frontend regression, keep browser version, viewport, feature flags, fixtures, and API responses consistent. For an API or data issue, control authentication, database state, and request payloads. The REST API testing guide can help structure repeatable request and assertion checks.

Merges, shallow clones, and skipped commits

Git can bisect histories containing merges, but the result must be interpreted in context. A merge commit may be the first commit where the failure becomes observable even though the underlying change came from one of its parents. After Git identifies a merge, inspect both parent histories and reproduce the issue on relevant branches.

A shallow clone may not contain the good revision or enough ancestry for a useful search. Fetch more history before starting, for example with git fetch --deepen=200 origin <branch>, or obtain the required range in a full clone. The exact amount to fetch depends on the repository and the known-good boundary.

Use git bisect skip only when a revision truly cannot be tested, such as a build break unrelated to the regression. Skipping too many commits can leave Git with an ambiguous range, so record why each skip occurred.

What to double-check

  • Good and bad endpoints: Confirm both classifications independently. If either endpoint is wrong, the final answer is not meaningful.
  • Test determinism: Repeat the test at least once when the result is surprising. Flaky results can send the search in the wrong direction.
  • Environment parity: Keep runtime versions, environment variables, generated assets, browsers, services, and test data consistent.
  • Build assumptions: Older commits may require different setup steps. Separate “the regression is present” from “this revision does not build.”
  • Uncommitted work: Stash, commit, or otherwise preserve local changes before switching revisions. Do not use a bisect session as a substitute for a backup.
  • Result verification: Test the reported commit and its parent. If both fail or both pass, revisit the endpoint definitions, test command, and skipped revisions.

Keep a short investigation note containing the bug symptom, good and bad commit identifiers, test command, environment details, skipped revisions, and the final conclusion. This turns a one-time debugging exercise into a useful handoff for a fix or code review.

Common mistakes

Starting with an uncertain boundary

“It probably worked around here” is not a reliable good marker. Find a commit where the behavior is demonstrably correct. If necessary, use release tags, deployment records, or an old reproducible test fixture to establish the boundary.

Classifying infrastructure failures as bad commits

A failed dependency download, missing service, or incompatible compiler does not prove that the application is broken at that revision. Repair the environment or return 125 from an automated script.

Adding workarounds, changing inputs, or switching browsers midway undermines the binary search. If the original test is invalidated by a historical change, stop, define a stable replacement, and restart with clearly documented criteria.

Forgetting to leave bisect mode

After the diagnosis, run git bisect reset. Check git status and confirm you are back on the intended branch before editing or committing a fix.

Assuming the first bad commit is the complete explanation

The commit identified by Git is the first point where the chosen symptom appears, not necessarily the only cause. Inspect related configuration, generated files, dependencies, merge parents, and follow-up commits before deciding on the fix.

When to revisit

Return to this checklist whenever a regression needs tracing through more than a few commits, especially before a release or during a planned maintenance cycle. Revisit the automation script when the build system, test runner, package manager, runtime, or monorepo layout changes. A script that once returned a clean pass or fail may later encounter a new setup failure that should be treated as a skip.

Also update the investigation notes when the repository adopts shallow CI checkouts, changes its merge strategy, or moves tests between packages. If the symptom involves browser loading, API calls, or performance rather than a straightforward unit test, pair bisect with focused diagnostics such as the Browser DevTools Network Tab Guide or the frontend performance audit checklist.

Final action checklist: preserve local work; define a repeatable test; verify a good and bad endpoint; start bisect; classify every revision carefully; skip only untestable commits; verify the reported commit against its parent; record the evidence; and run git bisect reset. Used this way, Git bisect is not just a command to remember—it is a repeatable debugging workflow for finding the commit that introduced a regression.

Related Topics

#Git#Debugging#Testing#Version Control#Developer Workflow
T

The Coding Club Editorial Team

Programming Tutorials 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.