Following my previous post about a sensible Git pull request template, I will continue with the Git theme. This time I will focus on displaying your Git log in a way that makes it much more readable.
Do you ever look at your commit history? Do you ever find yourself searching your recent (or not-so-recent!) commit history looking for a specific commit? Do you tag your deployments? If not, you’re probably missing a trick.
How many times have you heard or read this about making good commit messages, or making each commit atomic? Hopefully many times, because it is important. However, while these concepts are fairly easy to understand and adopt, it’s a little harder when it comes to your git history as a whole.
So what do I mean by a “clean” Git log? Well, let’s start by looking at something that you’ve almost certainly seen before. Think about how easy is it to understand what has happened here (the commits themselves aren’t important):
What if you found a bug and had to revert a commit, or even worse, roll back a bad deployment? Worse still, how do you even start trying to read and understand this kind of history? Well, you don’t. Trying to understand this mess is like trying to explain The Matrix to a 5 year old.
The above sample was taken from the oh-my-zsh git history from a few months back. However, taking a look at the more recent history in the same source code, you’ll see something like this:
What a difference! A clear, linear history that shows groups of related commits followed by a merge commit. Easy to read, easy to understand, easy to change. Much more like explaining Kung Fu Panda to a 5 year old.
So how do you actually do this?
Here is a simple workflow we follow to keep our Git history looking good.
- Do all your work in a feature branch. Raise a pull request.
- Another developer will check out your feature branch and rebase with master. This keeps the history linear.
- We sometimes squash some commits (using an interactive rebase) to keep each pull request manageable. Common-sense applies.
- Merge to master.
- Run the tests (the will pass of course!) and push the master branch.
I rebase a feature branch like this:
git pull --rebase origin master
That will rebase your feature branch with the remote master branch. Once that’s done, the merge to master becomes trivial:
git merge your-feature-branch --no-ff --log --no-edit
Enjoy your new, clean Git history.