Falling in love with git bisect

29 May 2022

Recently I found myself tracking down a handful of regressions: bugs I knew hadn’t existed just a week or two before. I vaguely knew that there was a git command that could help me, but I had never really put it to serious use. Now that I have used it, I find myself falling in love with git bisect.

bisect, in the style of all things git, is slightly arcane and clunky but powerful nonetheless. All you have to do is tell git a known-good commit and a known-bad commit, and it will guide you through an efficient exploration of your repository’s history. At each step of the process, bisect presents you with a commit and asks “is this commit good, or bad?” A quick test of your system and you can produce the answer (failing tests, incorrect behavior, broken build, what have you) and inform git; it can then continue with a binary search to find the offending change.

You can initiate bisect with

git bisect start

At any time, you can bail out of this operation with

git bisect reset

which is good to keep in mind if you find yourself tangled. Now that you’ve started the bisect, define the bounds by picking a commit that has “good” state and a commit that has “bad” state:

git bisect good my-good-commit

and

git bisect bad my-bad-commit

After you’ve specified your commits, git will check out the midpoint and ask you to evaluate it. Do whatever you need (run tests, inspect an app, check benchmarks) and then inform git that this commit is good or bad with a simple git bisect good/bad as desired. The process will repeat a few times until you find what you’re looking for!

This is where we come to a crucial caveat: your git history. I find that it’s best to squash intermediary commits when merging, resulting in a clean list of working commits. It aids in history explorations like this one, and means you don’t have to fight through a flurry of “wip: temp” and “fix lint” garbage commits. However, if you find yourself confronted with a commit that you cannot test, git bisect skip is your friend.

If you’d like to learn more, the git bisect docs have more detail and even explore the topic of automatic bisecting. Happy hacking!