How and Why to Squash Your Pull Request

- 12 minutes read - 2475 words

Many pull requests go through a cycle: programmer opens pull request, maintainer gives feedback, programmer makes changes, repeat until ready to merge, maintainer merges. Prior to the merge, the pull request can be messy, full of reverts, fixups, and WIP commits. In the end, those commits are noise. We can tell a better story by squashing the branch.

Consider this Git branch history:

7 e 3 e 7 4 2 2 e a 7 c 4 a 3 4 a 7 d f 6 7 e e 5 5 4 9 e a 7 a 7 c 1 d 4 c 5 b d 2 ( R T R O T H e e e o e E f s v o s A a t e p t D c r s t a t b o r r r e " e i O a i n p o k s g a o e s s p r u t s s e h i " / e n 3 g 8 p ) r h e e G v r o i e o o d u s t o c o m m e m r i g t e !

The final commit at the top, 724d574, has been approved to merge by the maintainer. But this branch is a mess. We have a commit that’s just refactoring (e2af5ac), two commits that cancel each other out (ea479cb and 77aee1d), and one that has failing tests (4c7ead2).

Some GitHub repos use squash merges, which squash this entire list down into one commit. That technique has its place, but you lose a ton of context by squashing 5, 10, or 20 commits into one. I’d prefer to squash it myself and choose what to highlight. So, let’s squash it!

⚠️ Disclaimer! This process alters history. Do it on a feature branch, not the default branch. If it’s part of a pull request, wait until the project maintainer asks you to do it– changing history on an open pull request can make an unfinished discussion difficult to follow.

The Squash

We’ll use git rebase, interactive mode via the --interactive flag, going back six commits to the start of our branch:

$ g i t r e b a s e - i n t e r a c t i v e H E A D ~ 6

A pro alternative is to use the parent branch as a reference. Our feature branch came from main, so lets use that:

$ g i t r e b a s e - i n t e r a c t i v e m a i n

This opens a git-rebase-todo file:

p p p p p p # # # # # # # # # # # # # # # # # # i i i i i i c c c c c c R C p r e s f x d T I H N k k k k k k e o , , , , , , , h f o o b m e w t 4 7 e 3 e 7 a m p r e s f e d s y e e c 7 a e 2 2 s a i e d q i x r e o v 7 a 4 3 a 4 e n c w i u x e o u e t e e 7 6 f d d k o t a u c p l r h a e 9 4 5 5 d s r s p i r , a d 1 c 7 a 7 d : = d = h = = n e t 2 d b 5 c 4 6 = e m i b u = u = r r s o f e T O R T R G b s s l u e v m e o e e e o 1 e u e u i n m c e y p s o v s f o 2 s s k o a o t t p e t a d . c e c e e c v n a u y s r c . o o o e b t a t t 7 m c m c " m b l r c r r o o 2 m o m o s m c e i e o e " e r 4 i m i m q a o n m m a O i m d t m t m u n m r e o m k o p n e 5 i , i a d m e v i e o a g r 7 t t s i - h e t r p s g 4 , b , h ( t o e s s s t e u " t r r e " i h ! o b t b , h d e v a n e n u u e e e r g t t s t b r T r e p o t u r e H y h r e o m t e d A t c e e d d p e s ; T h o r v d i l d t i m e i 6 t f d i t C n m o b o s o h O g e u b t r i c f e M , n s 1 h n a y M t 2 e a t r t I t e c m o d h a T h d o ( c e e r e m 6 o n p t e W o m m d r h l I r u i c m i e i i e L e t t o i n v s n x L b m t g i e e a m o c ) c B s a m u o u E e n e s m u t d s m s e L w ( s c i i d O i s a o t n S l ) g m ' g f T l ) e m s r . i s o b t l h m e o e g l t a l o b m p o e r s t t s o e a d g b . e o t t o m .

Our goal is to make the log atomic. In short, we want each commit to contain distinct, complete changes, that pass all tests, described by a coherent message.

Here are my notes on these commits:

  • 4c7ead2 Test breaker: this contributes to the solution, but it breaks tests. We want to keep it, but it can’t stand on its own as a single commit
  • pick 77aee1d Ooops: this is useless… it was a mistake.
  • pick ea479cb Revert "Ooops": this reverts the previous commit… also useless.
  • pick 3e36475 Test are passing here: this is important!
  • pick e2af5ac Refactoring the previous commit: same as above
  • pick 724d574 Good to merge!: same as above

With this in mind, I’d edit this file as such:

p d d s s s i c 7 e 3 e 7 k 7 a e 2 2 a 4 3 a 4 4 e 7 6 f d c e 9 4 5 5 7 1 c 7 a 7 e d b 5 c 4 a d O R T R G 2 o e e e o o v s f o T p e t a d e s r c s t a t t t r o o " e r b O i m r o p n e e o a g r a p s g k s s t e e " i h ! r n e g p h r e e r v e i o u s c o m m i t

What’s going on here?

  • Delete (d) the two commits that cancel each other out. Deleting the line from the manifest has the same effect
  • Squash (s) the three useful commits together ‘up’. Because we’re deleting everything that’s ‘up’, the parent will be 4c7ead2, AKA Test Breaker

An alternative to squash is fixup or f, which squashes the four commits and automatically picks the first commit message in the list to cover them all. I don’t like that solution here, because the first commit message (Test breaker) has become inaccurate.

Save and close the temporary file, and you’ll be in a new commit message editing window, with the three squash messages and the parent’s message all together:

# # T # T # R # G # # # # # # # # # # # e e e o T T s T s T f T o P w D i L N Y h h t h t h a h d l i a n a o o i e i i c i e t t t s u s b s a s t s t a h e e t s s c f r r o o s : r o a i i e i e i r i e ' a c e 7 m r s r a s s i s m # c o 2 2 m e s k p n e e ' t m a 4 a a t e t a t g t r n i m f d n c r h s h h g t w v a 5 5 d u c c e s e t e e e i e n a 7 s r o o i h ! r l S d c 4 r m m 2 n 3 e 4 l u r s r e b m n g r t t n e R G e n i i d d p h h b b d e o m t n t h r e e J a o f o a l a ' c e c e c u s n a d i y t s o r o v o c i l e e c n i m e m i m o g t t i e o m m m o m m n 3 i ( o o n d n e i i u i m o n 6 r g i s t t s t i r 1 i m . t o s t e 4 p c n e i f a m m c m d : r o g r n g e e o e m , 3 o m g g 4 e s s m s e 1 g m t e s s m s s a : r a h ! a c i a a i a s n 3 e n e o s g g t g a d 8 s d c m : e e e g s s p o m : : : e a 2 ; r m i n 0 d e m t f 1 o o v i s o e 6 n n i t . r m t e o p - o ) u w y t 0 : s h o y 5 d i u 0 d c l r m 0 6 o e e b m c s b m r h s 1 i e a a 2 t b n g a g e s e i s a n . b g o L r b i t r n s a e n s t c h h s e t ' a c m r o a t m i i m n n i ' g t . o n ' d d 6 b b 1 2 ' .

Now it’s time to write the squash message. If the issue at hand is issue #38, ‘Back button is broken’, then I’d change the first line of this file to this:

C # # # u s P w t l i o e t m a h e s r e ' # g e ' o n e t w s e i r l ' l b t a h b c e e k ' c i o g v m n i m o a i r t e b d a m , c e k s a s n b a d u g t e a t n o f n o e r m p y t o y u r m e c s h s a a n g g e e s a . b o L r i t n s e s t h s e t a c r o t m i m n i g t .

Here’s our squashed history:

4 e 7 6 3 d 3 ( H E A D i s s u e / 3 8 ) C u s t o m e r g o e s ' b a c k ' v i a b a c k b u t t o n

This is much better. Instead of sharing my messy thought process with the team, I’m just sharing the finished product. Force push it to GitHub, which is permissible because we’re on a personal feature branch:

$ g i t p u s h - f o r c e

Now we have a clean pull request that tells a coherent story and is ready to merge.

Fixing Mistakes

Is your rebase going wrong? Don’t panic. You can abort the rebase with:

$ g i t r e b a s e - a b o r t

Even with the rebase is complete, you can always travel back in time with git reflog. There is very rarely a situation with a rebase that you can’t undo.

Conclusion

Keeping the history of a big project tidy is a constant process. I’m always trying to make commits smaller, better organized, more coherent. Do your favorite project maintainer and your own projects a favor and work on a feature branch, and when finished, squash your commits. It will make your code and the project better.