In this tutorial, you will learn how to improve your GIT commit messages. You will learn about the Conventional Commits Standard as well as a linting tool called commitlint that you can install within your NPM powered project to ensure that you and your team adhere to beautiful commit messaging ☁️🌊🌈🦋✨
On the project you are currently working on, if you do a git log --pretty=oneline, what do you see? Do you see a commit history that is easy to read and looks like it has been written by a single person? Can you match each commit to a specification? Simply looking at a commit, can you go into whatever project management tool you use to learn more about why the code was written? On most projects that I encounter this does not happen. The commit history is usually filled with unhelpful messages like test,bug, orfix`.
When you try to debug a production issue, not having a clean and useful commit history wastes time. Having a clean commit history will help you understand your codebase. Unfortunately from my experience, if you trust the developers on your team to simply write a good commit message, you are walking into a life of constant disappointment. New team members start and do not know what to do, in an emergency people forget, finally some developers won't see the value and won't bother. This is why a linter is useful. You can force good developer habits onto your team. After a day of adding a linter, people naturally start to create good commit messages without thinking about it. Luckily, adding such a tool to your project is easy. Today you will learn how 🔥🔥🔥
Conventional Commits Standard
First, let us start by defining what a good commit message should include? A title, a description, the ability to use semantic versioning? If you have a commit history like this:
It is very hard to understand what is going on. What about if the commit history looked like this?
The second example is obviously much better, so how do you write good commit messages? Trying to invent your own standard is a waste of time and effort. Instead, I recommend using an existing convention, why invent the wheel if you do not have to? This is why I recommend adopting the conventional commit standard (used in the second example above). This standard is the most widely used commit messaging standard out there. The conventional commit standard is a guide that defines how you should write your commit messages. The standard specifies a message should include a type, a scope (like your JIRA number), a description (in lower-case). You can also add an optional body and footer. I have used conventional commit on many projects, after you get used to them, they are good and you should try them. Using convention commits means you can also have automatic semantic versioning within your projects (with some extra packages not covered here).
Saying that you will use the conventional commit standard and making sure that everyone on the team adheres to the standard are two very different things. This is where CommitLint comes in. CommitLint will add a check within your NPM powered projects to prevent anyone from committing code unless the commit message is written following the convention commit standard. A second package called husky can also be used to include a git pre-commit hook. These two things combined will prevent anyone from committing without following the standard. Ye haw 🤠
How To Install CommitLint
To get this working within your project, you will need to install commitlint and husky. This can be done using these commands (notice the --save-dev):
Next, you will need to add some config in package.json:
Now, create a file called commitlint.config.js within the root of the project. Within this file, add this config:
Next, you will need to add a husky hook. First, install husky using the script created above:
After installation, you should see a folder called .husky in your project. If you do not see this folder, something has gone wrong. Assuming husky is installed, it is time to create the GIT pre-hook:
This command should create a new file within the .husky directory called commit-msg. Paste the below config into it:
That is everything installed and configured, it is time to test the hook works 💥. In a terminal, add your files using a GIT add:
Create a commit message that fils the rules, e.g.:
The linter should prevent the commit from succeeding. If this happens, you know you are onto a winner and it is wokring. You can test a valid commit like this:
That is all you need to know to get started with commit message linting on your project. If you want to see a project where this is set-up and working, you can find one over on my Github here. Job done! Happy coding 🤘
