Get Started | Website

Lint commit messages

Demo generated with svg-term-cli

cat docs/assets/commitlint.json | svg-term --out docs/public/assets/commitlint.svg --frame --profile=Seti --height=20 --width=80

• 🚓 Be a good commitizen
• 📦 Share configuration via npm
• 🤖 Tap into conventional-changelog

Contents

• Get Started | Website
• Contents
• What is commitlint
  • Benefits of using commitlint
• Getting started
• CLI
• Config
• Shared configuration
• Documentation
• API
• Tools
• Roadmap
• Version Support and Releases
  • Releases
• Related projects
• License
• Development
  • Install and run

What is commitlint

commitlint checks if your commit messages meet the conventional commit format.

In general the pattern mostly looks like this:

type(scope?): subject  #scope is optional; multiple scopes are supported (current delimiter options: "/", "\" and ",")

Real world examples can look like this:

chore: run tests on travis ci

fix(server): send cors headers

feat(blog): add comment section

Common types according to commitlint-config-conventional (based on the Angular convention) can be:

• build
• chore
• ci
• docs
• feat
• fix
• perf
• refactor
• revert
• style
• test

These can be modified by your own configuration.

Benefits of using commitlint

• Why Use Conventional Commits?
• "The perks of committing with conventions" (Talk slides)

Getting started

• Local setup - Lint messages on commit with husky
• CI setup - Lint messages during CI builds

CLI

• Primary way to interact with commitlint.
• npm install --save-dev @commitlint/cli
• Packages: cli

Config

• Configuration is picked up from:
• .commitlintrc
• .commitlintrc.json
• .commitlintrc.yaml
• .commitlintrc.yml
• .commitlintrc.js
• .commitlintrc.cjs
• .commitlintrc.mjs
• .commitlintrc.ts
• .commitlintrc.cts
• .commitlintrc.mts
• commitlint.config.js
• commitlint.config.cjs
• commitlint.config.mjs
• commitlint.config.ts
• commitlint.config.cts
• commitlint.config.mts
• commitlint field in package.json
• commitlint field in package.yaml
• Packages: cli, core
• See Rules for a complete list of possible rules
• An example configuration can be found at @commitlint/config-conventional

Important note about Node 24+

Node v24 changes the way that modules are loaded, and this includes the commitlint config file. If your project does not contain a package.json, commitlint may fail to load the config, resulting in a Please add rules to your commitlint.config.js error message. This can be fixed by doing either of the following:

• Add a package.json file, declaring your project as an ES6 module. This can be done easily by running npm init es6.
• Rename the config file from commitlint.config.js to commitlint.config.mjs.

Shared configuration

A number of shared configurations are available to install and use with commitlint:

• @commitlint/config-angular
• @commitlint/config-conventional
• @commitlint/config-lerna-scopes
• @commitlint/config-nx-scopes
• @commitlint/config-patternplate
• @commitlint/config-workspace-scopes
• conventional-changelog-lint-config-atom
• conventional-changelog-lint-config-canonical

⚠️ If you want to publish your own shareable config then make sure it has a name aligning with the pattern commitlint-config-emoji-log or commitlint-config-your-config-name — then in extend all you have to write is emoji-log or your-config-name.

Documentation

Check the main website.

API

• Alternative, programmatic way to interact with commitlint
• Packages:
• format - Format commitlint reports
• lint - Lint a string against commitlint rules
• load - Load shared commitlint configuration
• read - Read commit messages from a specified range or last edit
• See API for a complete list of methods and examples

Tools

• commitizen adapter
• prompt

Roadmap

commitlint is considered stable and is used in various projects as a development tool.

Ideas: conventional-changelog/commitlint#94

Version Support and Releases

• Node.js LTS >= 22.12.0
• git >= 2.13.2

Releases

We're not a sponsored OSS project. Therefore we can't promise that we will release patch versions for older releases in a timely manner.\ If you are stuck on an older version and need a security patch we're happy if you can provide a PR.

Related projects

• conventional-changelog Generate a changelog from conventional commit history
• commitizen Simple commit conventions for internet citizens
• create-semantic-module CLI for quickly integrating commitizen and commitlint in new or existing projects

License

Copyright by @marionebl. All commitlint packages are released under the MIT license.

Development

commitlint is developed in a mono repository.

Install and run

git clone git@github.com:conventional-changelog/commitlint.git
cd commitlint
pnpm install
pnpm build # run build tasks
pnpm start # rebuild on change (tsc -b --watch)
node @commitlint/cli/cli.js # run CLI

For more information on how to contribute please take a look at our contribution guide.