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.
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?
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.
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:
> 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
> git log <last release> HEAD --grep feat # All new features since the last release
23ad9ad feat(proxy): Added support for bi-directional streams
The general structure of a Karma based message is:
<type>(<scope>): <subject>
<body>
<footer>
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:
The scope is a description of what is the part of the code that was affected by the change. Example scopes may be:
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.
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:
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
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ł
Python Developer
At Brave we specialise in IT Staff Augmentation, and Software Development Consulting. We help you to get your project done.