commitlint
Overview
commitlint (@commitlint/cli, v21 at the time of writing) lints a commit message against a rule set; the usual rule set is @commitlint/config-conventional, which enforces type(scope?): subject. It requires Node.js 22.12 or newer. It runs in a Git commit-msg hook (typically via husky) and in CI. Valid messages let tools such as semantic-release, release-please, changesets or conventional-changelog derive version bumps and changelogs.
Instructions
Step 1: Install and add the hook (husky v9)
npm install -D @commitlint/cli @commitlint/config-conventional husky
npx husky init
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg
npx husky init also creates .husky/pre-commit containing npm test, which makes every commit fail in a project without tests. Edit or empty that file if you do not want it.
Step 2: Configure
Create commitlint.config.mjs (or commitlint.config.js with "type": "module", .cjs, .ts, .commitlintrc.*, or a commitlint key in package.json).
// commitlint.config.mjs
export default {
extends: ['@commitlint/config-conventional'],
rules: {
// [severity, applicable, value]; severity 0 off, 1 warning, 2 error
'scope-enum': [2, 'always', ['auth', 'api', 'billing', 'ui', 'deps']],
'scope-case': [2, 'always', 'kebab-case'],
'header-max-length': [2, 'always', 72],
},
}
The default type-enum is build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test. If you override type-enum, repeat the types you still want, including revert. Default config-conventional limits headers and body/footer lines to 100 characters and forbids sentence-case subjects and trailing periods.
Step 3: Try it
echo "updated stuff" | npx commitlint # exit 1: subject and type may not be empty
echo "feat(auth): add Google OAuth login" | npx commitlint # exit 0
git commit -m "fix(api): handle null response from /users" # hook runs commitlint
Step 4: Lint in CI
# .github/workflows/commitlint.yml
name: commitlint
on: [pull_request]
jobs:
commitlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
Other useful forms: npx commitlint --last (latest commit), --from origin/main (everything since main), --config path for a non-default config. If you squash-merge, lint the PR title instead of the individual commits.
Examples
Example 1: Add commit linting to an existing repo
User request: "Make everyone on the team use conventional commits."
Run Step 1 and Step 2, empty .husky/pre-commit if the repo has no npm test, and commit commitlint.config.mjs and .husky/. Then git commit -m "updated stuff" is rejected with type may not be empty [type-empty], and git commit -m "feat(billing): add annual plan" succeeds. Add a prepare script ("prepare": "husky", which husky init sets) so teammates get hooks after npm install.
Example 2: Restrict scopes to the monorepo packages
User request: "Only allow scopes that match our package names."
Set 'scope-enum': [2, 'always', ['web', 'api', 'worker']]. Then echo "feat(mobile): add push" | npx commitlint exits 1 with scope must be one of [web, api, worker] [scope-enum], while fix(api): retry on 503 passes.
Guidelines
- Hooks can be bypassed with
git commit --no-verify; keep the CI check as the enforcement point.
- Merge and revert commits generated by Git are ignored by default; do not disable that.
subject-max-length does not exist in config-conventional by default; the header limit is header-max-length (100).- Breaking changes use
feat!: or a BREAKING CHANGE: footer and map to a major version; feat maps to minor, fix to patch.
- commitlint only lints messages; it does not generate changelogs. Pair it with a release tool.
- On older Node versions install an older commitlint major; v21 needs Node 22.12 or newer.