Integrating commitlint with Conventional Commits

Setting Up commitlint

commitlint is a tool that checks commit messages against a set of rules. Combined with Git hooks, it can prevent non-conforming commits from being created, ensuring your entire commit history follows the Conventional Commits specification.

Installation

npm install -D @commitlint/cli @commitlint/config-conventional

Configuration

Create commitlint.config.js at your project root:

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

This enforces:

• Valid commit type (feat, fix, docs, etc.)
• Subject line format (lowercase, no period)
• Header max length (100 characters by default)
• Body and footer formatting rules

Git Hooks with Husky

Install Husky to run commitlint automatically:

npm install -D husky
npx husky init
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

Now every git commit will be validated before it is created.

Custom Rules

You can customize rules for your team:

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // Enforce specific scopes
    'scope-enum': [2, 'always', [
      'auth', 'api', 'ui', 'db', 'config', 'deps'
    ]],
    // Require scope
    'scope-empty': [2, 'never'],
    // Limit subject length to 50
    'subject-max-length': [2, 'always', 50],
    // Allow only specific types
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'build', 'ci', 'chore', 'revert'
    ]],
  },
};

CI Integration

Add commitlint to your CI pipeline to validate PR commits:

# GitHub Actions
- name: Lint commits
  uses: wagoid/commitlint-github-action@v5

Handling Failures

When commitlint rejects a commit, it shows a clear error:

✗ type must be one of [feat, fix, docs, ...]
✗ subject must not end with period
✗ header must not be longer than 100 characters

Fix the message and try again. The commit was not created, so no amend is needed.