Git bisect for regressions

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.

DebuggingPack: Debugging101 linesgit-bisect-regression

Install

Run one command — it saves SKILL.md into your agent's skills folder. Restart the agent and the skill is picked up automatically.

Claude Code — macOS, Linux
mkdir -p ~/.claude/skills/git-bisect-regression && curl -fsSL https://anymodel.org/en/skills/debugging/git-bisect-regression/SKILL.md -o ~/.claude/skills/git-bisect-regression/SKILL.md
Codex, Cursor — macOS, Linux
mkdir -p ~/.agents/skills/git-bisect-regression && curl -fsSL https://anymodel.org/en/skills/debugging/git-bisect-regression/SKILL.md -o ~/.agents/skills/git-bisect-regression/SKILL.md
Claude Code — Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.claude\skills\git-bisect-regression" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/debugging/git-bisect-regression/SKILL.md -UseBasicParsing -OutFile "$HOME\.claude\skills\git-bisect-regression\SKILL.md"
Codex, Cursor — Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.agents\skills\git-bisect-regression" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/debugging/git-bisect-regression/SKILL.md -UseBasicParsing -OutFile "$HOME\.agents\skills\git-bisect-regression\SKILL.md"

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/debugging/git-bisect-regression/SKILL.md

SKILL.md

Raw

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.
git status --short
git log --oneline -n 20
git checkout <good-sha> && <test command>; echo $?
git checkout <branch> && <test command>; echo $?

Manual bisect

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:

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:

#!/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 · License: CC BY 4.0

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Debugging