Commitlint — Lint Commit Messages to Enforce Conventions

Introduction

Commitlint is a linting tool for Git commit messages. It validates every commit against configurable rules, most commonly the Conventional Commits specification. By catching malformed messages at commit time, Commitlint ensures that your Git history is structured enough for automated changelog generation, semantic versioning, and meaningful release notes.

What Commitlint Does

• Validates commit messages against a configurable set of rules at commit time
• Enforces the Conventional Commits format (type, scope, subject, body, footer)
• Integrates with Husky or other Git hook managers to run on every commit
• Provides clear error messages showing exactly which rules a commit message violates
• Supports custom and shared configurations for team-wide consistency

Architecture Overview

Commitlint parses each commit message into structured parts (type, scope, subject, body, footer) using a parser based on the conventional-changelog ecosystem. It then runs the parsed result through a set of rules defined in the configuration file. Each rule can be set to warning or error level with configurable parameters. The tool reads configuration from commitlint.config.js, .commitlintrc, or the commitlint field in package.json.

Self-Hosting & Configuration

• Install the CLI and a config preset with npm install --save-dev @commitlint/cli @commitlint/config-conventional
• Create commitlint.config.js extending @commitlint/config-conventional for standard rules
• Wire into Husky by adding a commit-msg hook that runs commitlint --edit $1
• Customize individual rules by overriding them in your config file (e.g., max header length)
• Use @commitlint/config-angular or create a custom shared config for non-standard conventions

Key Features

• Supports the full Conventional Commits specification including breaking change footers
• Shareable configuration packages let teams publish and reuse commit rules across repositories
• Plugin system for adding custom rules beyond the built-in set
• CLI can lint a range of commits for retroactive checks in CI pipelines
• Prompt CLI (@commitlint/prompt-cli) guides developers through writing valid messages interactively

Comparison with Similar Tools

• Commitizen — Guides developers through writing commits via prompts; Commitlint validates after the fact
• semantic-release — Reads Conventional Commits for versioning; Commitlint enforces the format that semantic-release depends on
• git-cliff — Generates changelogs from structured commits; does not enforce commit formats
• Husky — Runs Git hooks; Commitlint is the linting tool that Husky triggers on the commit-msg hook
• Conventional Changelog — Generates changelogs from commit history; Commitlint ensures commits follow the expected format

FAQ

Q: What is a valid Conventional Commit message? A: The format is type(scope): subject where type is feat, fix, chore, docs, etc. Scope is optional. Example: feat(auth): add OAuth2 login flow.

Q: Can I use Commitlint without Husky? A: Yes. You can run Commitlint in CI against a range of commits using commitlint --from HEAD~5 or integrate it with any Git hook manager.

Q: Does Commitlint work with monorepos? A: Yes. You can enforce scope rules that match package names and share a single Commitlint config at the repository root.

Q: Can I allow custom commit types beyond the standard set? A: Yes. Override the type-enum rule in your config to add custom types like build, perf, ci, or any identifier your team uses.

Sources

• https://github.com/conventional-changelog/commitlint
• https://commitlint.js.org