commitlint

📓 Lint commit messages

18,679 stars TypeScript Markdown Skills API Spec #commit#conventions#git#lint
AI Prompts & Specs

Repository: conventional-changelog/commitlint


Stars: 18453

README.md

Get Started | Website

Lint commit messages

<p align="center">
<img width="600" src="docs/public/assets/commitlint.svg">
</p>

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

[![npm latest][2]][3] [![node compatibility][13]][14] [![Github Actions][4]][5]

- 🚓 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:

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

Real world examples can look like this:

text
chore: run tests on travis ci

text
fix(server): send cors headers

text
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 >= 18
- git >= 2.13.2

Releases

Security patches will be applied to versions which are not yet EOL.\
Features will only be applied to the current main version.

| Release | Initial release |
| -------------------------------------------------------------------------------- | --------------- |
| v19 | 02/2024 |
| v18 | 10/2023 |

EOL is usually after around a year.

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.

- 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

sh
git clone [email protected]:conventional-changelog/commitlint.git
cd commitlint
yarn
yarn run build # run build tasks
yarn start # run tests, again on change
yarn run commitlint # run CLI

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

[0]: https://img.shields.io/badge/stability-stable-green.svg?style=flat-square
[1]: https://nodejs.org/api/documentation.html#documentation_stability_index
[2]: https://img.shields.io/npm/v/@commitlint/cli.svg?style=flat-square
[3]: https://npmjs.org/package/@commitlint/cli
[4]: https://github.com/conventional-changelog/commitlint/actions/workflows/CI.yml/badge.svg
[5]: https://github.com/conventional-changelog/commitlint/actions/workflows/CI.yml
[8]: https://img.shields.io/badge/stability-experimental-orange.svg?style=flat-square
[9]: https://nodejs.org/api/documentation.html#documentation_stability_index
[10]: https://img.shields.io/npm/v/@commitlint/cli/next.svg?style=flat-square
[13]: https://img.shields.io/node/v/@commitlint/cli.svg
[14]: https://nodejs.org/en/about/previous-releases