Introduction to Commitlint and Semantic Commits for Beginner Devs

[Werliton Silva]

Have you ever wondered why some development teams have super organized, easy-to-understand, and standardized commit messages? That’s thanks to semantic commits and tools like commitlint.

In this article, I’ll show you how to start using these practices in your project with simple language and practical examples you can apply today.

What Are Semantic Commits?​

Semantic commits are commit messages that follow a standardized structure. This helps you quickly understand what was done, enables automation (like changelogs), and improves collaboration between developers.

Basic Structure​

<type>(<scope>): <description>

• type: the kind of change (e.g., feat, fix, docs, etc.)
• scope: optional, indicates the part of the project affected
• description: a brief summary of the change

Examples​

feat(auth): add Google login
fix(MYPROJ-1234): fix layout bug
docs(readme): update installation instructions
refactor(api): improve search performance

Installing Commitlint​

Let’s set up commitlint in a Node.js project. If you don’t have a project yet, you can create one with:

npm init -y

1. Install the dependencies​

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

2. Create the config file​

Create a file named commitlint.config.js in the root of your project:

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

Validating Commits with Husky​

To make sure all commits follow the standard, we’ll use Husky to run commitlint automatically.

1. Install Husky​

npm install --save-dev husky

2. Enable hooks​

npx husky install

Add this to your package.json:

"scripts": {
  "prepare": "husky install"
}

3. Create the commit hook​

• Create the .husky folder (if it doesn't already exist*)*:

Run the command npx husky init. This will initialize Husky and create the .husky folder in the root of your project.

npx husky init

• Create the hook file directly:

Inside the .husky folder, create a new file with the name of the hook you need. For Commitlint, the file should be named commit-msg.

# Use the 'touch' command on Unix/Linux systems or 'New-Item' in PowerShell (Windows)
touch .husky/commit-msg

• Add the validation script to the file:

Open the .husky/commit-msg file with a text editor and add the command that will run Commitlint. The standard command is npx --no-install commitlint --edit ${1}.

#!/usr/bin/env sh
npx --no-install commitlint --edit "$1"

Note: The npx --no-install command is more efficient because it uses the version of Commitlint that's already installed in your project (via package.json), rather than installing it again on every run.

Done! Now, if someone tries to make a commit that doesn’t follow the pattern, it’ll be blocked.

Testing It Out​

Try making a commit with the message below:

git commit -m "fix layout bug"

This commit will be rejected because it doesn’t follow the format.

Now try:

git commit -m "fix(MYPROJ-1234): fix layout bug"

This one will be accepted!

Conclusion​

Using semantic commits with commitlintis a simple and powerful way to keep your project organized and professional. Even if you’re just starting out, it’s worth adopting this practice right away.

If you want to go further, you can integrate it with tools like Conventional Changelog, semantic-release, and more.

Did you enjoy this content? Let me know how you organize your commits!

Continue reading...

 

Join 𝕋𝕄𝕋 on Telegram
Channel PREVIEW: