Introduction to Committing with Conventional Commit

Introduction

Conventional commit is a specific form of committing which gives software developers a uniform system for organizing and describing their changes, making it easier to keep track of updates. This type of commit generally follows a strict and consistent format, making it easier to understand what changes were made and why.

The conventional commit typically follows a specific format, such as:

<type>[optional scope]: <description>

Where the type is subject of the commit, it indicates the type of change that was made and should be one of the following types:

feat: a feature or new addition to the project
fix: a bug fix
refactor: refactoring of code or changes to the project infrastructure
style: changes to the formatting, white-space, etc.
docs: changes to documentation
perf: a code change that improves performance
chore: minor changes, such as updating the version of a dependency, fixing a typo, etc.
...

The scope is optional and is used to indicate the part of the project that was changed, such as api, ui, database, etc.

The description is a short description of the change, it should be written in the imperative mood, such as "change" instead of "changed" or "changes".

Example:

feat(api): send an email to the customer when a product is shipped

fix: prevent racing of requests

Why use conventional commit?

Conventional commit helps to ensure that commits are organized and consistent. This makes it easier to read and understand what changes have been made and why. It also makes it easier to track down and understand related issues and pull requests.

By following the conventional commit format, teams can also easily create commit messages that follow the same structure and format. This makes it easier to review and understand the changes that have been made, as well as ensure that changes are documented in the same way each time.

In addition, conventional commit is a great way to keep the project’s codebase organized and consistent. This helps to make sure that the codebase is easy to maintain and read, as well as reducing the amount of time spent debugging and refactoring.

Set up conventional commit to your project

In this post, I will show you how to set up conventional commit to your project using commitlint

Install commitlint and its dependencies:

$ npm install -g @commitlint/cli @commitlint/config-conventional

Add a commitlint config file to your project:

Using this command to create a config file with basic configuration:

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

The file should have the following content:

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

Add husky to lint commits before they are created:

$ npm install husky --save-dev

Activate hooks with the following command:

$ npx husky install

Your should see the following output:

husky - Git hooks installed

and a new .husky folder should be created in the root of your project.

I would highly recommend adding a postinstall script in the package.json file to automatically install husky hooks after installing dependencies:

"scripts": {
	"postinstall": "husky install"
}

Add a commit-msg hook to lint commits:

$ npx husky add .husky/commit-msg  'npx --no -- commitlint --edit ${1}'

You should see a commit-msg file created in the .husky folder.

And that’s it ! Now, whenever you commit, commitlint will check your commit message and make sure it follows the conventional commit format.

Let’s try it out with an un-conventional commit message:

$ git commit -m "Using commitlint and husky to lint commits"

The commit should fail with the following error:

⧗   input: Using commitlint and husky to lint commits
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky - commit-msg hook exited with code 1 (error)

As you can see, commitlint has detected that the commit message is not following the conventional commit format and has provided a helpful error message.

Now, let’s try it again with a conventional commit message:

$ git commit -m "feat: add commitlint and husky to lint commits"

The commit should succeed with the following output:

[main b40785f] feat: using husky to lint commits
	3 files changed, 27 insertions(+)
	create mode 100755 .husky/commit-msg

Conclusion

Conventional commit is a great way to ensure that commit messages are organized and consistent. By following the conventional commit format, teams can easily create commit messages that follow the same structure and format, making it easier to review and understand the changes that have been made.

Therefore, it’s important to use this type of commit when developing projects so that changes are well-documented and tracked.

Happy committing