Skip to content
Get packs

Guide · Open source

How to use commitlint: install, configure and lint commit messages

Updated · written with AI from the project's own documentation and checked against our catalogue data

commitlint is a command-line tool that checks whether your git commit messages follow a set pattern, such as starting with a type like feat, fix or docs. This guide is for developers and teams who already use or want to adopt the conventional commit format. After reading it, you will know how to install commitlint, write a configuration file, and run checks on commits or in CI.

commitlintconventional-changelog/commitlint · ★ 18.8k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have Node.js 22.12.0 or newer and git 2.13.2 or newer.
  2. 2Install the CLI. Run npm install --save-dev @commitlint/cli in your project.
  3. 3Add a configuration file. Create a .commitlintrc or commitlint.config.js file, or add a commitlint field to package.json.
  4. 4Choose rules or a shared config. Extend a shared configuration such as @commitlint/config-conventional, or define your own rules.
  5. 5Set up a commit hook. Follow the local setup guide to lint messages on each commit with husky.
  6. 6Add a CI check. Follow the CI setup guide to lint messages during CI builds.

What commitlint checks in a commit message

commitlint checks if your commit messages meet the conventional commit format. The general pattern is a type, an optional scope in parentheses, and a subject. Multiple scopes are supported, with the delimiter options "/", "\" and ",".

  • chore: run tests on travis ci
  • fix(server): send cors headers
  • feat(blog): add comment section
  • Common types include build, chore, ci, docs, feat, fix, perf, refactor, revert, style and test.
  • These types can be changed with your own configuration.
type(scope?): subject

Install commitlint with npm

Install the CLI as a dev dependency with npm. commitlint requires Node.js 22.12.0 or newer (LTS) and git 2.13.2 or newer.

  • Check that your Node.js and git versions meet the requirements before installing.
npm install --save-dev @commitlint/cli

Create a commitlint configuration

commitlint reads its configuration from one of several files. The source lists .commitlintrc (with .json, .yaml, .yml, .js, .cjs, .mjs, .ts, .cts or .mts extensions), commitlint.config.js (and the matching .cjs, .mjs, .ts, .cts or .mts variants), or a commitlint field in package.json. The README points to @commitlint/config-conventional as an example configuration.

Rules are listed in the project's rules reference. Shared configurations such as @commitlint/config-conventional can be installed and extended.

  • .commitlintrc.json
  • commitlint.config.js
  • commitlint field in package.json
  • Shareable configs follow the naming pattern commitlint-config-your-config-name and are referenced by the short name in extends.

Run commitlint on each commit with husky

The README links to a local setup guide that lints messages on commit using husky. This is the common way to run commitlint automatically each time someone commits. Follow the local setup guide at commitlint.js.org for the exact hook steps, since the README does not spell them out.

Run commitlint in CI builds

commitlint can also run during CI builds. The README links to a CI setup guide for this. Running the check in CI catches messages that bypassed local hooks.

Use commitlint from code

The CLI is the primary way to use commitlint. The README also describes an alternative programmatic API, with packages for formatting reports, linting a string against rules, loading shared configuration, and reading commit messages from a range or the last edit.

  • @commitlint/format formats reports
  • @commitlint/lint lints a string against rules
  • @commitlint/load loads shared configuration
  • @commitlint/read reads commit messages

What people use it for

  • Keeping git history readable by enforcing a shared commit format across a team.
  • Feeding conventional commit history into conventional-changelog to generate changelogs.
  • Sharing one set of commit rules across several repositories through a shareable config.
  • Blocking non-conforming commit messages during CI builds.

Frequently asked questions

Is commitlint free to use?

Yes. The packages are released under the MIT license, according to the README. Check the LICENSE file in the repository for full terms.

What are the requirements for commitlint?

The README lists Node.js 22.12.0 or newer (LTS) and git 2.13.2 or newer. Environments without Node.js cannot run it.

How do I install commitlint?

Run npm install --save-dev @commitlint/cli in your project. This installs the CLI as a dev dependency.

Does commitlint have a graphical interface?

No. The README describes only a command-line interface and a programmatic API.

What is the difference between commitlint and commitizen?

commitlint checks that commit messages follow a format. The README lists commitizen as a related project that focuses on writing commit messages in that format, and it provides a commitizen adapter.

Can I use commitlint without a commit convention?

The tool only makes sense once a format is agreed on. Without a convention, there are no rules for it to enforce.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

commitlint suits teams that use or plan to adopt conventional commits, especially those generating changelogs or sharing rules across repositories. Projects without an agreed commit format, or environments without Node.js 22.12.0 or newer, should choose something else. Consider husky or commitizen if you need related tooling for hooks or writing commits.

Install options & downloads