Having an usable git log

The commit history of most projects I’ve worked on was simply not legible. They were a homogeneus set of meaningless stuff. Mainly short messages like "Fix the test" and auto generated "Merge branch fix/4839 [...]" texts. You could find some expressive messages, but looking for them was tedious.

I think not taking care of a shared git log is not nice, and basically a bad practice. The log is a relevant tool and should be easy to use. It simplifies debugging and makes the project progress more visual.

I decided to research solutions and try to solve the problem for my current team.

The first, main step to achieve that clean log is to learn how and when to squash commits. To squash commits means to unify them into only one. Check it out:

Squashed

You can squash n commits using:

git rebase -i HEAD~n

Or just squash the last commit and your current staging:

git commit --amend

The pros of squashing can be summarized in consistency and clarity.

But some serious cons could emerge too if not done correctly. When you squash commits, you are rewriting the git history. Messing with that is dangerous, as pulling a history change from a remote is problematic, to say the least. Moreover, squashing commits in a team will only improve things if everyone does it. So you not only need to do something dangerous, but force everyone to do it too. Not sounding like a good idea anymore!

Luckily, there is a way to securely operate with the squashing concept: only squash when you’re sure nobody will be able to pull that poisonous history change. And that is when your working branch only exists locally.

This means you can securely squash your stuff just before opening a pull request (normally the point in which your working branch becomes public) and just before merging (if you delete the branch afterwards).

It doesn’t seem that dangerous now to start squashing. But you would be introducing the rebase command into your team workflow. And that is not only risky, but a clockmaking bomb.

As a final solution, there is a more secure approach: to use your software hosting tool to automatically squash before merging. GitHub, for example, offers you the posibility to change their Merge button to Squash and merge. Doing that, everyone will squash at the right moment, and you won’t be bringing more possible human errors into the workflow as they won’t start using git rebase or any other boldness.

You can read more about using GitHub to start squashing on this post.

We have started to squash commits in my team. We haven’t had any problems by now, and you can definitely tell the difference with the log. There are still some more work to do to achieve greatness in our git log, but this was a successful first step. ✨