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
- Related projects
- License
- Development
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.mtscommitlint.config.jscommitlint.config.cjscommitlint.config.mjscommitlint.config.tscommitlint.config.ctscommitlint.config.mtscommitlint field in package.jsoncommitlint 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 [email protected]: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.
