Find the Commit That Broke Your Tests with git bisect run

When a regression appeared somewhere across dozens of commits, reading every diff is slow and biased. git bisect performs a binary search, and bisect run lets a focused test classify each candidate automatically.

When to use

A test passes in an older release but fails on the current branch.
The first bad change is buried in a long series of human and agent commits.
You can express the regression as a reliable command with a meaningful exit code.

Example

The auth test passes at tag v1.4.0 but fails at HEAD. Git checks out candidate commits and runs only src/auth.test.ts until it identifies the first failure.

TL;DR

Give Git one bad and one good commit plus a test command; it finds the culprit.

bash

git bisect start HEAD v1.4.0
git bisect run npm test
git bisect reset

Steps

1
Mark the range
First argument is bad, second is a known good commit or tag.
bash
```
git bisect start HEAD v1.4.0
```

Write a focused check

Exit 0 = good, 1–124 = bad, 125 = skip this commit.

bash

cat > /tmp/check.sh <<'EOF'
#!/bin/sh
npm ci --silent || exit 125
npx vitest run src/auth.test.ts
EOF
chmod +x /tmp/check.sh

3
Run it
Let Git repeatedly check out a candidate and execute the script; do not edit the working tree while the search is running.
bash
```
git bisect run /tmp/check.sh
```
4
Read the result and go back
Git prints "<sha> is the first bad commit".
bash
```
git show <sha>
git bisect reset
```

Gotchas

Keep the check script outside the repo so checkouts do not change it.
Run one targeted test, not the whole suite: faster and fewer false results.
Use exit 125 for commits that do not build.
Small commits make bisect precise; one giant agent commit makes it useless.

Cheat sheet

git bisect start <bad> <good>	Start with a range
git bisect run <cmd>	Automate good/bad
git bisect good \| bad \| skip	Mark manually
git bisect log	Show decisions
git bisect reset	Return to original branch

Sources

git-bisect documentation

Reviewing agent output? CodeCrab reviews pull requests locally with your own AI tools.