How to Identify the Breaking Commit With Git Bisect

- 8 minutes read - 1681 words

Some code is broken, and you can’t figure out why. Maybe there are a lot of changes to consider, and identifying that breaking change seems impossible. Or, maybe you’re curious about how things generally break in your organization. The tool you need is git-bisect.

Git bisect conducts a binary search through your Git history to find a commit of interest. In this post, I’ll show how it works with an example.

A Caveat

For bisect to be useful, you must be committing atomically. If your practice is to squash-merge PRs, or commit swaths of unrelated code with each commit, a bisect may only tell you that something broke when you merged in a mega PR. That isn’t typically new or useful information.

Start the Bisect

Back to our scenario: you’re on main and something is broken. A white screen. A style regression. An inexplicable network error.

Tell Git this as your starting point with start:

$ ( g g i i t t ) b - i [ s m e a c i t n | s b t i a s r e t c t ] - $

Now we’re at main in a bisect state, as you can read in the new prompt.

Mark a Bad Reference

The reference we have checked out, main is bad– it demonstrates the bad behavior. We note that this commit is broken with bad:

$ ( g g i i t t ) b - i [ s m e a c i t n | b b a i d s e c t ] - $

You can verify that it did something with git show, or any command that shows refs:

$ c o g m i m t i t s h 8 o b w e c 3 1 7 a ( H E A D m a i n , r e f s / b i s e c t / b a d )

Note the bad ref at the end.

Find a Good Reference

Now, we need to find a commit in the past where things worked. I usually jump back at least twenty commits to start. When in doubt, jump farther.

$ N o g t i e t : c s h w e i c t k c o h u i t n g H E t A o D ~ ' 2 H 0 E A D ~ 2 0 ' .

Test your code again. Is it still broken? If so, jump back the same amount of commits or more.

Once you find a place where it isn’t broken, that’s a ‘good’ commit. Let’s make a note:

$ B [ i 6 g s 9 i e d t c 8 t 0 b i f i n a s g 4 e : a c c t 2 j 2 a g d o r 4 o e b d v d i 3 s 8 i e o 0 n b s 8 0 l 2 e a f b t 8 7 t d o 4 a t 6 e a s 3 t 2 7 a 9 f c t 4 e 0 r ] t M h e i r s g e ( r p o u u l g l h l r y e q 5 u e s s t t e p # s 8 ) f r o m r e p o / b r a n c h

As the prompt explains, even though we’ve jumped back forty commits, we are only five steps from an answer!

Continue the Bisect

Now, we continue the bisect. Test your code on the new commit. Is it still broken? If so, make a note:

$ B [ i 5 g s 6 i e 9 t c 8 t 8 b i a i n j s g c e : 4 c 3 t 1 a 1 b b 9 a r 7 d e 2 v b i a s f i 4 o 3 n 9 s 8 4 l a e 1 f 8 t f 4 t 5 o 8 0 t 9 e 7 s 1 t c c a 2 f 4 t 5 e 0 r ] t R h e i m s o v ( e r o d u e g p h r l e y c a 4 t i s o t n e p w s a ) r n i n g

If it isn’t broken, swap good for bad.

Continue this process until there are no more commits to test. You’ll see a conclusion like this:

( c c A D g 6 o u a e 1 i 6 m t t x t d m h e a f ) 2 i o : T m i - c t r h p l [ 2 : i l e v d c s e 0 a 6 S T . c . j 6 o u m g h 2 a d m e i e a . 9 2 e g m n 2 1 c A h s g 1 d 2 D u t p e ~ e d e g e d 1 f a v w c , | 4 j 2 o b a a < 8 r | 4 i a 9 d k s a 1 e 1 ? 6 i e f d v 4 n c 1 e @ : 😅 s t 0 f e 5 e ] 7 4 x 7 r - d a a : t $ a a m 0 i 9 a p 0 o g 1 f l n i 3 1 e 2 s t 6 0 . 0 ( c 7 c 1 + b 4 d o 8 ) i 3 a m , s 8 9 > - e 6 1 0 2 c 1 3 7 t 2 6 0 d 9 c 0 e b 6 4 l a f 3 e d 8 t i 6 i s 1 o 2 n t 9 s h 6 ( e f - ) f i r s t b a d c o m m i t

Use show to learn more about your bad commit.

$ g i t s h o w c 6 6 d 2 c 2 d a j a 9 1 d e f 4 a a a f 1 0 7 d a 9 1 3 6 c 4 3 8 6 1 2 9 6 f

Lastly, exit with reset (not stop or abort, as I often mistype 😡):

$ S w g i i t t c h b e i d s e t c o t b r r e a s n e c t h ' m a i n '

To summarize all the commands:

# $ # $ # $ # $ # S g T g T g T g C t i e i r i e i o a t s t a t s t n r t v t t t b b e c b i i y i l h y i n s o s e o s u e u e b c u e e c r c a k r c t t c o t u f k u f n s e b w t e g t t a a a a o i a t d r H t o l r u d E u d t r A r t e n D e h ~ e a c < a n o n n b d m > d a m d c i f o t i c n s n o f d m i m r o i m u t t t i h i s a f t i i d i t e t n ' w t s o i r f b k i r s e o d k . e o . n r . c o n t i n u e j u m p i n g b a c k )

Git Bisect Run With Automated Tests

Have a program that returns 0 for success or 1 for error, like a unit test? Use it to automate your bisect:

$ $ $ $ $ g g g g g i i i i i t t t t t b b c b b i i h i i s s e s s e e c e e c c k c c t t o t t u s b t g r t a o u a d < o n r a d t n < y r s g p o e o c d s r p e e f c > / d e m o n s t r a t e s _ t h e _ f e a t u r e _ s p e c . r b >

run will complete the entire bisect for you, using your test!

Conclusion

Why bother with this technique? Why not just find and fix the issue, and move on?

My advice is to try it a few times when you’re stuck debugging and see. When I have used it, I’ve felt like I’m able to answer a question that nobody else can within a reasonable amount of time. There’s something empowering and precise about saying “this broke in the Rails upgrade.” It turns your Git history into a useful resource for learning how to quickly fix things and how things break generally in your organization.

git-bisect is an incredible tool. I hope it helps you.