---
name: git-bisect-regression
description: Finds the commit that introduced a regression using git bisect, manually or automated with git bisect run and a script, and handles flaky or unbuildable commits with skip. Use when something worked before and now fails.
---

# Git Bisect for Regressions

Bisect does a binary search over history. With N commits between good and bad it needs about log2(N) tests. Use it when you know a past state that worked.

## Before you start

1. Make sure the working tree is clean. Bisect checks out other commits; uncommitted changes get in the way. If the tree is dirty, ask the user whether to commit or stash first. Do not discard changes.
2. Note the current branch so you can return: `git rev-parse --abbrev-ref HEAD`.
3. Find a good commit: a tag, a release, a date, or ask the user. If unknown, try older commits yourself until the test passes.
4. Write a test that detects the bug in one command with a clear result. It must be deterministic. Run it on the bad commit (must fail) and the good commit (must pass) before bisecting.

```sh
git status --short
git log --oneline -n 20
git checkout <good-sha> && <test command>; echo $?
git checkout <branch> && <test command>; echo $?
```

## Manual bisect

```sh
git bisect start
git bisect bad                # current commit is broken
git bisect good <good-sha>
# git checks out a middle commit; build and run the test
git bisect good               # or: git bisect bad
# repeat until git prints "<sha> is the first bad commit"
git bisect log                # record the result
git bisect reset              # return to the original branch
```

Always run `git bisect reset` at the end, even after errors.

## Automated bisect

When the test is a script, let git drive it:

```sh
git bisect start <bad-sha> <good-sha>
git bisect run ./check.sh
git bisect reset
```

The script exit code decides each step:

- `0`: this commit is good.
- `1` to `124`, `126`, `127`: this commit is bad (except 125).
- `125`: this commit cannot be tested, skip it.
- `128` and above, or a signal: bisect aborts.

Keep the script outside the repository or untracked, because checkouts replace tracked files. Example:

```sh
#!/bin/sh
npm ci --silent || exit 125          # cannot install: skip
npm run build --silent || exit 125   # does not compile: skip, not a verdict
npx vitest run tests/price.test.ts   # exit code 0 or 1 is the verdict
```

Distinguish "bug present" from "cannot build". A broken build is not the bug; return 125.

## Skipping commits

- Manual: `git bisect skip`, or `git bisect skip <sha1>..<sha2>` for a range that does not build.
- If many commits are skipped, git may report that the culprit is one of several commits. Narrow it by reading those diffs or fixing the build issue temporarily in an untracked way.

## Flaky tests

- If the failure is intermittent, a single run is not a verdict. Make the script repeat: run up to N times and mark bad if any run fails, or mark good only after N passes.
- Measure the failure rate on the known bad commit first. If it fails 1 in 10, repeat at least 30 times on candidates.
- If you cannot make the test reliable, say so; bisect will give a wrong commit.

## After you find the commit

1. Run `git show <sha>` and read the diff. Confirm the change really explains the failure; check that reverting only that change on the bad commit makes the test pass (do this on a temporary branch).
2. Check whether it is a merge commit. If so, both parents passed: the bug comes from how the branches combine or from the conflict resolution; compare `git diff <sha>^1 <sha>` and `git diff <sha>^2 <sha>`. (Only with `git bisect start --first-parent` does a merge mean "somewhere in the merged branch"; then bisect that branch separately.)
3. Fix the code properly; do not just revert unless the user agrees.
4. Add a regression test.

## Report format

- Good and bad commits used, test command.
- First bad commit: sha, author date, subject.
- Why that change causes the bug (the specific lines).
- Skipped commits and why, and any doubt about the result.
- Proposed fix.

## Pitfalls

- Never run `git bisect` on a dirty tree and never `git reset --hard` or `git clean` to fix it without asking the user.
- Dependencies, lockfiles and build caches differ between commits; reinstall or clean build artifacts when the test depends on them.
- Environment data (database schema, migrations) may not match old commits; the failure can come from that, not from the code.
- Do not leave the repo in the middle of a bisect. Check `git bisect log` and reset.
- Never push from a detached HEAD during bisect.

Source: [AnyModel skills catalog](https://anymodel.org/en/skills) · License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
