Improve your commits with Conventional Commits

Learn how to use CommitLint and Husky to add structure and improve the readability of your commits

If you’ve been in the world of development for some time it is very likely that the image above feels familiar to you, every software developer already wrote bad commits at some point in their career, and who can shame them?

Writing consistent, meaningful commit messages are hard, that’s why in this guide we’ll learn a way to improve commits messages with Conventional Commits.

What are Conventional Commits?

The Conventional Commits specification is a simple convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history.

Below you can see the structure that Conventional Commits follows.

<type>

The type is intended to describe the category of your change. The most common types are: build, chore, ci, docs, feat, fix, perf, refactor, revert, style and test.

[optional scope]

The second, optional part is the so called scope. The scope Describes the module affected by your change.

<description>

The description is where describe the alterations made by your commit.

The easiest way to get an idea of what it looks like is by seeing some examples. Here are some minimal commit messages satisfying the rules.

You can learn more about how to format your commits by reading the conventional commits specification.

Husky and CommitLint

Now that you know about Conventional Commits you can already start following the specification rules by your own, but easier said than done, right? To help us maintain a good commit pattern we can use two Javascript libraries, CommitLint and Husky, first let’s talk about CommitLint.

CommitLint checks if our commit messages meet the conventional commit format, so we don’t have to worry about making a mistake, for as long as we set the right rules CommitLint will be there for us.

If you’re programming in a language other than Javascript don’t worry, there are a lot of other libraries like CommitLints for other languages, you just need to find the one that suits your needs.

Installing CommitLint

Let’s start by installing CommitLint and their CLI on your repository as a development dependency.

Windows

npm install --save-dev @commitlint/config-conventional

Mac/Linux

npm install --save-dev @commitlint/{config-conventional,cli}

Now let’s configure commitlint to follow conventional commits specification.

First start by creating commitlint.config.js file, you can do it either manually or by your terminal.

echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

Inside our commitlint.config.js we can set some rules, for this article I’ll use the rules from commitlint’s rules configuration example, but feel free to check their docs for a better explanation about all different rules and settings that commitlint have for you.

Now that we’re done with CommitLint you could start using their CLI to check our commits, however, I prefer using Husky to do that automatically for me.

Husky

Husky is a library that allows us to use Git Hooks on our commits. Git hooks permit custom scripts to be ran on your repository before a set action, like a commit or a push. We’ll use this in conjunction to CommitLint to check if our Commit is following the rules we’ve set on our commitlint config file.

Setup

npm install husky --save-dev

Now let’s tell our package.json file to use Husky hooks with commitlint rules:

Now we can test if everything is working.

Conclusion

Good commit messages are important for maintaining any long-term project. It helps you to keep track of all of your commits and know which changes were made in each commit and with Conventional Commits you can start doing that extremely fast, I highly recommend you give it a try and learn more about it on their official site.

If you wanna check the configuration files I created on this project then you can get them on my GitHub’s repository.