The other day I was poking around in a github repository and came across this commit message:

Not that I needed to know that much about what this person was committing at the time, but I couldn’t help but think how unhelpful this commit message would be if someone needed to understand the project.

I have also been guilty of creating less-than-descriptive commit messages - I'm sure we've all been there. If you want to see some truly hilarious commit messages you can check out whatthecommit.com.

At my work we started using Commitizen which is based on Conventional Commits specification. It took a minute to get used to but after a few days, I could see how much value it was adding to the code base.

Breaking down commit size

Because it breaks commits down into categories, it forces you to only add relevant files to one category.

Buh-bye editing 30 files and committing them all in one go. I mean, you still could do that but you will feel a slight pang of guilt every time you add a feature change in with your test changes.

After using the tool for a few days, I started thinking about good stopping points in my work where I could commit - with the intention that I could make my messages make the most sense. For example, when working on a feature that also included some refactor work, I would try to just do the refactor first, commit that, and then start working on the new functionality. Looking back at the commit messages when browsing files and seeing the type of change that was made, helps so much for granularity and for knowing what to expect from a certain commit.

More descriptive messages

While other people on the internet might have already been splitting their commit messages into subjects and bodies, I was not. I’ve now realized, the longer description in the body is so helpful for describing the nuances of the changes you have made. Even if its just for you to go over before you make your pull request, it will help you understand why you did what you in a way more thorough way - provided you actually add a thorough description.

At my work, we’ve gone a step further to create a custom command line tool that makes your pull requests for you on Github with the pull request description being a list of your git commits. At first, I was worried this wasn’t enough. How could 100 character commit messages tell you everything you need to know about the code changes? But then, I had a lightbulb moment: the commits already ARE supposed to tell you everything about the code changes. I just wasn’t making my commits well enough. Once I started breaking things down by commit category and providing better commit messages (mainly through the longer descriptions), my pull requests were back up to the level they used to be before when I would write the description myself and have subpar commit messages.

I encourage everyone to set up Commitizen and try it out for a few days. I think it will make future you way happier when you are looking back at your code and thinking, “What the heck was I thinking?”