Git Better #1 - See more with a commit message convention

December 27, 2019

11 min

Many of us don’t pay much attention to commit messages. But when we need to look for a specific change, or we are wondering why was an addition made, problems appear. What if I told you, there is a simple and easy way to greatly improve the experience with git history.

Troubling reality

Let’s be honest, we all have seen (and been a part of) such git logs:

ad8621a Fix a bug in the feature

16b36c6 Addressed a PR comment

23ad9ad You can now download form correctly through the main website

21672sd Typing for mypy

These messages try to describe what changes have been made, but ultimately are not much of use. Why?

They don’t point to place in the code where the change was made
They don’t specify what was the type of the change, making it impossible to use a filter
Each one of them is written in a different style.

All of these problems may be solved by adopting a git commit message convention into the project, and today I am going to show you one - Karma.

What is Karma?

Today, we are not talking about famous religious-based “you get what you do”. However, that analogy is quite fitting as karma will sooner or later get you, if you are not using proper commit messages.
The Karma I want to show you is a git commit message convention, birthed from theAngularJS Git Commit Conventions google document, adapted to be used with any project and language. It aims to provide more useful, clear and precise information when browsing the git history, while also helping to easily achieve other goals:

Automatically generate changelog - When your git messages follow a convention, it is much easier to generate a changelog

> git log <last tag> HEAD --pretty=format:%s # All commits since the last release

23ad9ad feat(proxy): Added support for bi-directional streams

21672sd fix(proto): Fixed missing type annotation

Filter out unimportant commits - Using unified descriptions for a type of changes that are being introduced we can easily look through the history and pick only the interesting ones

> git log <last release> HEAD --grep feat # All new features since the last release

23ad9ad feat(proxy): Added support for bi-directional streams

How to use it?

The general structure of a Karma based message is:

It is really simple to remember and once you start using it, you will almost never have to consult the reference.
As a simplification, we can state that each line can have a maximum of 80 characters and the second line must always be blank.

For <type> there are following allowed types:

feat - for all new features, or ones that changed behavior
fix - bug fixes in ready features
docs - documentation, both in and outside code
style - formatting, typos
refactor - refactoring production code
test - all things test related

The scope is a description of what is the part of the code that was affected by the change. Example scopes may be:

service
proxy
runner
etc.

In the body, you should include a sentence on why were the changes made. Be descriptive! If someone looked this far inside your commit, you can be sure they will appreciate every bit of information they can find. The official Karma documentation is very specific that imperative, present tense should be used, but my opinion is that it is not something you should worry about more than the quality of the description.

In the footer, you can (if they are being used in the project) reference issues. Multiple issues may be used at the same time.

Using all that knowledge we can produce an example:

fix(service): Verify the content type that is returned to the adapter

API can respond with text/plain content type instead of JSON.

To ensure proper operation it is verified before further processing.

Closes #112

It is looking good, right?

Further and more precise explanations can be found on the official Karma website, which I highly recommend to go through for reference.

Why should I bother if I never use git log?

You may say: “What you wrote looks nice, but I honestly can’t remember the last time I actually used git log and had trouble because of badly written git messages.”. And I have to agree, during everyday work it rarely happens that we need to use git log extensively. Here are some additional thoughts that may convince you:

Good commit messages are like backup, you think you don’t need one until you do.
The best thing about adopting a convention is that it is fully customizable. As long as you state the rules and stick to them, it will already be beneficial. For example, if you want the minimal version, just take the first line of Karma formatted message. Well written subject line should be enough in most scenarios, while still providing all profits of the complete approach.

minimal fix(service): Verify the content type that is returned to the adapter

ambitious API can respond with text/plain content type instead of JSON.

To ensure proper operation it is verified before further processing.

full Fixes #112

Think about a situation where you are handed over the project from other developers/company. Which kind of commit messages would you prefer? There always will be someone who takes over your code. Maintain your project in a way that you are not ashamed when they do.
Maybe you would be using your git history more if it was better structured, not the other way around.

Closing off

If you are convinced, share the idea with your team and try sticking to Karma rules for your next project. You can also convert to the convention in an ongoing one. Changing git messages will rarely break anything in your environment, so it doesn’t hurt to try, it is never too late to Git Better.

This article is a part of the ongoing series “Git Better with Bravelab”. In the next one, we are gonna cover cherry-picking. We will discuss when it is a good practice and how to avoid common errors using it.

‍

Paweł Glimos

Python Developer