DEV Community

Cover image for How to Standardize Commit Messages with Commitlint and Custom Rules
Werliton Silva
Werliton Silva

Posted on

How to Standardize Commit Messages with Commitlint and Custom Rules

#webdev #programming #beginners #productivity

“Hey, which Jira task is this commit related to?”
That question started popping up more and more in our team. And that’s when we realized: it was time to standardize our commit messages.

The challenge: connecting code to context

In our team, every Jira task has a unique identifier like TWSF-1234. But not everyone remembered to include it in their commits. The result? It was hard to track what was being delivered and why.

That’s when we decided to use Commitlint to enforce that every commit includes the task ID in the scope field. And more than that - we created a custom rule to make it happen.

What is Commitlint?

Commitlint is a tool that checks your commit messages against a set of rules. It helps keep your Git history clean, consistent, and easy to understand.

You can use predefined rules (like @commitlint/config-conventional) or create your own. We went with both.

Creating a custom rule

Here’s our commitlint.config.js file:

module.exports = {
    extends: ['@commitlint/config-conventional'],
    rules: {
        'twsf-task-scope': [2, 'always'],
    },
    plugins: [
        {
            rules: {
                'twsf-task-scope': ({ scope }) => {
                    const regex = /^TWSF-\d+$/;
                    const isValid = regex.test(scope);
                    return [
                        isValid,
                        'Scope must follow the pattern TWSF-<task-number>, e.g., TWSF-1234',
                    ];
                },
            },
        },
    ],
};
Enter fullscreen mode Exit fullscreen mode

What does this config do?

  1. Extends the conventional commit rules.
  2. Adds a custom rule called twsf-task-scope.
  3. This rule checks if the scope in the commit message matches the pattern TWSF-.

✅ Valid commit example: 

feat(TWSF-1234): add export report button
Enter fullscreen mode Exit fullscreen mode

❌ Invalid commit example: 

fix(report): fix export bug
Enter fullscreen mode Exit fullscreen mode

This second commit would be rejected with the message:

Scope must follow the pattern TWSF-, e.g., TWSF-1234

How to apply this to your project

1 - Install Commitlint and the required packages:

npm install --save-dev @commitlint/{cli,config-conventional}
Enter fullscreen mode Exit fullscreen mode

2 - Create the commitlint.config.js file with the configuration above.
3 - Integrate it with Git using a commit hook (via Husky):

  • 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
Enter fullscreen mode Exit fullscreen mode
  • 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"
Enter fullscreen mode Exit fullscreen mode

The result: better traceability, less confusion

After applying this rule, our commits became much more organized. Every delivery is clearly linked to a Jira task, making reviews, deployments, and even audits easier.

If you’re looking to bring more clarity to your project, creating custom rules with Commitlint is a great move. It’s simple, effective, and keeps your team aligned.

Did this help? Let me know in the comments how your team handles commit message standards!

Top comments (0)