Skip to content

conventional-changelog/commitlint

Repository files navigation

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

npm latest node compatibility Github Actions

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

Contents


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

Getting started

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
    • commitlint.config.js
    • commitlint.config.cjs
    • commitlint.config.mjs
    • commitlint.config.ts
    • commitlint.config.cts
    • commitlint field in package.json
  • Packages: cli, core
  • See Rules for a complete list of possible rules
  • An example configuration can be found at @commitlint/config-conventional

Shared configuration

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

⚠️ 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

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
v18 10/2023
v17 05/2022
v16 12/2021
v15 11/2021
v14 10/2021
v13 05/2021
v12 02/2021
v11 09/2020

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.

Related 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
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.