When Should a Merge Be Squashed?

I was still fairly new to Git when I ran into a question so basic that nobody seemed to have answered it anywhere: "When should a merge be squashed?"

Squashing a merge means taking all the commits that would normally be replayed individually on your target branch and collapsing them into a single commit.

Here's the rule of thumb I've settled on: squash when all the commits in the branch deal with one topic.

For example, imagine you have a branch dedicated to speeding up one particular method. Each time you squeeze out more performance, you commit. After a few days you've got several commits and a beautifully fast implementation ready to merge back to master. This is a perfect candidate for a squashed merge — your commit message should explain what you did and why it's faster.

git merge --squash speed-up-the-method

An unsquashed merge makes more sense when you're merging a development branch that already contains a well-organized series of commits, each covering a distinct topic. In that case, you want the individual commit messages preserved in your history.

git merge dev/v1.2.3

With an unsquashed merge, your repository keeps the original commit messages intact, giving you a richer and more detailed history.