Find the commit that broke your app with git bisect
Short answer: When something worked last month and is broken now, and you can't tell which of the hundreds of commits since then caused it, use git bisect. You mark one commit as good and one as bad, and Git checks out the commit halfway between them for you to test. Each answer halves the search, so even a long history narrows to the guilty commit in a handful of steps. If you can test with a script, git bisect run does the whole search for you.
The problem bisect solves
Regressions are common in business apps: the checkout total rounds wrongly, a report page has slowed to a crawl, an email template has lost its logo. Often nobody notices for weeks. By then, dozens of people's commits stand between the last known good version and today, and reading every diff is hopeless.
Git's documentation describes git bisect plainly: it uses a binary search algorithm to find which commit in your project's history introduced a bug. Binary search is the trick of guessing the middle of a range and throwing away the half that can't contain the answer. With a thousand commits in range, you need about ten tests rather than a thousand.
Before you start
- Know how to test. You need a reliable way to tell "good" from "bad": a page you load, a test you run, a command whose output you check.
- Find a known good point. A release tag, last month's deploy, or any commit where you're confident the bug didn't exist. Check it actually is good before you begin.
- Commit or stash your current work. Bisect checks out old commits, so you need a clean working tree.
- Note what changes between versions. Database migrations, dependency versions and configuration files may change across old commits, so you may need to reinstall dependencies at each step.
Step by step
git bisect startgit bisect badmarks the current commit (usually today's broken version) as bad.git bisect good v2.3.0marks a known-good tag or commit.- Git checks out a commit in the middle. Build or run the app and test the behaviour.
- Tell Git the result:
git bisect goodorgit bisect bad. - Repeat until Git prints the first bad commit, with its author, date and message.
git bisect resetreturns you to where you started.
Once you have the commit, read its diff. The cause is usually obvious once you know where to look, and the commit message often explains what the change was meant to do.
When a commit can't be tested
Some commits in the middle won't build, or are broken for an unrelated reason. Use git bisect skip and Git will choose a nearby commit instead. If many commits are skipped, the result may be a small range of possible culprits rather than one, which is still far better than starting from scratch.
If your terms aren't really "good" and "bad", for example you're looking for when a page became fast rather than slow, Git lets you use your own words, such as old and new, so the prompts make sense.
Automating with git bisect run
If you can write a script that exits successfully when the code is good and fails when it's bad, Git can run the whole search without you. The documentation sets the rules: the script should exit with code 0 if the current code is good, and with a code between 1 and 127 (except 125) if it's bad. Exit code 125 tells Git to skip that commit. Any other exit code aborts the bisect.
Practical scripts include:
- A single unit test that captures the bug.
- A command that loads a page locally and checks for a piece of text.
- A timing check that fails if a report takes longer than a set threshold.
Start the bisect with the good and bad commits, then run git bisect run ./check.sh. Make sure your script installs dependencies or runs migrations if those change across the range, and keep it outside the repository's tracked files so it's available at every checkout.
Tips for a smooth search
- Use
git bisect logto save your progress. If you make a mistake,git bisect replaycan replay the log after you edit out the wrong answer. - Narrow by path. If you know the bug lives in one area,
git bisect start -- path/to/folderlimits the search to commits that touched it. - Watch merge-heavy histories. If your team merges many branches, the
--first-parentoption follows only the main line, which can make results easier to read. - Write the test first. The script you write for bisect is also the regression test you should add to the codebase afterwards.
A worked example
Take a hypothetical Perth furniture retailer whose quote calculator started rounding delivery charges oddly. The last release known to be correct was three months old, with a few hundred commits since. A developer wrote a short test that fed the calculator one known order and checked the delivery line, marked the old release good and the current main branch bad, and ran git bisect run with the test. Within minutes, Git named a commit that had changed a shared currency helper for a different feature. The fix was a few lines, and the test went into the suite.
FAQ
Do I need the whole history locally?
You need the commits between your good and bad points. A shallow clone may not have them, so fetch the full history first.
Can I bisect a bug in production data?
Bisect checks code, not data. Reproduce the bug with a copy of the relevant data on your machine or staging server.
What if I answer good or bad by mistake?
Use git bisect log, remove the wrong line, and run git bisect replay on the edited file.
Does bisect work with any Git host?
Yes. It runs entirely on your local copy of the repository.
If you're chasing a regression and want help narrowing it down, tell us what changed and what broke.