Qvantor logo QvantorInfrastructure, explained plainly
Dev Tools

Git Bisect to Find the Commit That Broke Your Build

The build passed on Monday and fails on Thursday, and there are 140 commits in between. Reading them one by one is how a fifteen minute bug becomes a lost afternoon, and git bisect exists precisely so you never have to do that again.

A developer's desk with a laptop showing a long commit history in a terminal and a notebook with commit hashes crossed out

The build passed on Monday and fails on Thursday, and there are 140 commits in between. Reading them one by one is how a fifteen minute bug becomes a lost afternoon, and git bisect exists precisely so you never have to do that again.

Git bisect runs a binary search over your history. You mark one commit as good and one as bad, Git checks out the commit halfway between them, you test it, and the range halves. With 140 commits you need at most 8 tests. With 1,000 commits you need 10.

How git bisect works in plain terms

Every bisect session has three ingredients: a known good commit, a known bad commit, and a test that tells them apart. The test can be you clicking through the app, a single failing unit test, or a script that exits with code 0 for good and 1 for bad.

Git does not care how you decide. It only needs your verdict on each commit it hands you. After each verdict it discards half of the remaining suspects. When one commit is left, Git prints it with its author, date and message, and you know exactly which change introduced the problem.

The search is only as good as your verdicts. Mark one commit wrong and Git will confidently point at an innocent change. That is the single most common way bisect sessions go sideways, and we will come back to it.

A manual git bisect session step by step

Start from a clean working tree. Stash or commit anything in progress first, because bisect will check out old commits and your uncommitted changes will get in the way.

  1. Run git bisect start to open the session.
  2. Run git bisect bad to mark the current commit, usually the tip of main, as broken.
  3. Run git bisect good followed by a commit hash or tag you trust, such as v2.3.0 or last week's release commit.
  4. Git checks out a commit in the middle and tells you roughly how many steps remain. Build it, run your check, then type git bisect good or git bisect bad.
  5. Repeat until Git prints "is the first bad commit" along with the culprit.
  6. Run git bisect reset to return to the branch you started on.

If a commit in the middle does not build for an unrelated reason, type git bisect skip. Git picks a neighbour instead. Skipping a few commits is fine. Skipping dozens means your history has long stretches of broken builds, which is a separate problem worth fixing.

Automating the search with git bisect run

Manual bisecting is fine for visual bugs. For anything a script can detect, let Git drive. After the start, bad and good steps, run git bisect run followed by a command, for example git bisect run npm test or git bisect run ./check.sh.

Git runs the command on each midpoint commit and reads the exit code:

  • Exit code 0 means good.
  • Exit codes 1 to 127, except 125, mean bad.
  • Exit code 125 means skip this commit, which is useful when the build itself fails.
  • Anything above 127 aborts the whole session.

The best test script is narrow. Running the full suite of 2,000 tests on every step is slow and noisy, because an unrelated flaky test can flip a verdict. Write a script that checks the one behaviour you care about. On a medium sized Node project I usually end up with something that installs dependencies, runs one test file, and exits. A session over 300 commits then finishes in about nine runs of under a minute each, while I make coffee.

If your project already has a task runner, add a target for this. The pattern from our guide to a Makefile task runner for small projects works well: a make bisect-check target that builds and runs a single check keeps the command short and repeatable for the whole team.

Dependencies that change between commits

Old commits often need old dependencies. If your lockfile changed during the range, your script must reinstall on every step, or you will test new code against stale packages and get nonsense. The same goes for database migrations and generated files. Put the reinstall and regenerate steps in the script, even though it costs time.

Why the usual advice about small commits misses the point

You will often hear that bisect only works if every commit is tiny. I disagree with the emphasis. Size matters less than one property: every commit on the branch you search should build and pass its own tests.

A branch of fifty small commits where every third one is broken is worse to bisect than a branch of twelve medium commits that each work. Broken commits force skips, skips widen the final range, and you end up with "the bug is somewhere in these four commits" instead of a single answer.

So the practical habit is not "commit less code at a time". It is "never commit something that does not build". Hooks help here. A quick pre-commit check that compiles and lints, like the ones in our piece on git pre-commit hooks that small teams keep using, keeps history bisectable without anyone thinking about it. If your team squash merges pull requests, you get the same property at the main branch level for free, because each merge commit passed CI.

Common git bisect mistakes and how to avoid them

  • A dirty working tree. Leftover local edits travel with you across checkouts and change results. Start clean.
  • Testing the wrong thing. If the symptom is "the export button returns a 500", test that exact request, not the whole page.
  • Caches between steps. Build caches, compiled assets in a dist folder, or a running dev server can hide the real state of a commit. Clear them in your script.
  • Flaky tests. If a test fails one run in ten, run it three times per step and only call it bad if it fails consistently.
  • Forgetting to reset. You stay in a detached HEAD state until you run git bisect reset. Commit nothing until you do.

When a session goes wrong midway, git bisect log prints every verdict so far. Save it to a file, edit out the bad line, then use git bisect replay with that file to resume from the corrected state instead of starting over.

Once you have the culprit, read its diff before blaming anyone. Often the first bad commit is correct on its own and only exposes a problem elsewhere, such as a config default or an environment difference. If the bug only reproduces on one machine, our article on how a local setup drifts away from production is the next place to look.

Frequently asked questions

How many steps does git bisect take?

Roughly the base 2 logarithm of the number of commits in the range. For 100 commits that is about 7 steps, for 1,000 about 10, and for 10,000 about 14. Skipped commits can add one or two more.

Can git bisect find when a bug was fixed instead of introduced?

Yes. Start the session with git bisect start, then use the custom terms feature, or simply invert your thinking and mark the fixed commits as bad and the older broken ones as good. The first "bad" commit Git reports is then the one that fixed it.

Does git bisect work with merge commits?

It does. Git searches the full commit graph, so it may land inside a merged feature branch. If you only want to search the merge commits on main, newer Git versions let you restrict bisect to first parents, which is handy when feature branches contain many work in progress commits.

IV
Ilkka Varis

Ilkka has run mail servers for small companies since the days of hand edited DNS zones.

More posts by Ilkka

More in Dev Tools

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu haskell iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr webtech1223411 wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto