This package has been deprecated

Author message:

renamed to commitlint:


2.1.1 • Public • Published

Lint commit messages

conventional-changelog-lint stability

npm version Travis branch AppVeyor branch

  • 🚓 Enforce commit conventions
  • 🤖 Plays nice with conventional-changelog
  • 📦 Supports shareable configuration


Fetch it with npm

npm install --save-dev conventional-changelog-lint


conventional-changelog-lint provides a command line and node interface.


conventional-changelog-lint demo

The command line interface reads .conventional-changelog-lintrc resolves extends configurations.

❯ conventional-changelog-lint --help
  conventional-changelog-lint - Lint commit messages against a conventional-changelog preset and ruleset
  [input] reads from stdin if --edit, --from, --to are omitted
  --color,-c    toggle formatted output, defaults to: true
  --edit,-e     read last commit message found in ./git/COMMIT_EDITMSG
  --extends,-x  array of shareable configurations to extend
  --from,-f     lower end of the commit range to lint; applies if edit=false
  --preset,-p   conventional-changelog-preset to use for commit message parsing, defaults to: angular
  --to,-t       upper end of the commit range to lint; applies if edit=false
  --quiet,-q    toggle console output


git hook

As a commitmsg git-hook with "husky"

    "scripts": {
      "commitmsg": "conventional-changelog-lint -e"

Last commit

As part of npm test

    "scripts": {
      "test": "conventional-changelog-lint --from=HEAD~1"

Lint all commits in Pull Request

You can lint all commits in a PR by passing all commits that are present in SOURCE_BRANCH but unavailable in BASE_BRANCH:

conventional-changelog-lint --from=BASE_BRANCH to=SOURCE_BRANCH

Most of the time BASE_BRANCH will be master for Github Flow.

This assumes SOURCE_BRANCH is available on your local checkout. This is not true by default for all PRs originating from clones of a repository.

Given you'd like to lint all commits in PR origination from branch remote-test on the repository targeting master on

cd test # make sure CWD is in your repository 
git remote add other-name
git fetch other-name
conventional-changelog-lint --from=master --to=other-name/test

See scripts/ for an example on how to obtain SOURCE_BRANCH from a Github clone automatically on Travis.


Commit Linting on CI has to handle the following cases

  • Direct commits
  • Branch Pull Requests
  • Fork Pull Requests

An exemplary implementation is provided as bash script working on Travis CI.

# Force full git checkout
before_install: git fetch --unshallow
  - ./scripts/ # [1] scripts/

[1]: See scripts/ for reference


The programming interface does not read configuration by default, it has to be provided as second parameter.

import lint from 'conventional-changelog-lint';
const report = lint(
  'docs: add node api interface usage',
    preset: {},
    configuration: {}

To achieve the same behavior as with the command line interface you can use the provided utility functions:

import lint from 'conventional-changelog-lint';
import {
} from 'conventional-changelog-lint';
const report = lint(
  'docs: add node api interface usage',
    preset: await getPreset('angular'),
    configuration: await readConfiguration('conventional-changelog-lint')


conventional-changelog-lint is configured via .conventional-changelog-lintrc and shareable configuration.

When no .conventional-changelog-lintrc is found it will use the angular shareable config. See the documentation there for default rules.

When a .conventional-changelog-lintrc is found it will not load any preset unless specified via extends configuration.


  "extends": ["angular"]

Array of shareable configurations to extend. Configurations are resolved as conventional-changelog-lint-config-${name} and have to be installed. See npm search for available shareable configurations.

⇨ See shareable-config for details


  "preset": "angular"

conventional-changelog preset name to use for parsing of commit messages.

⇨ See conventional-changelog for details


  "rules": {
    "body-leading-blank": [1, "always"],
    "header-max-length": [1, "always", 72],
    "subject-full-stop": [1, "never", "."]

Rules applicable to the linted commit messages. By default all rules are turned off via a level of 0. They can be enabled by shareable configuration, such as the angular config, which is loaded by default.

⇨ See rules for details


Patterns to exclude from linting

wildcards: {
  merge: [
    '/^(Merge pull request)|(Merge (.*?) into (.*?)$)/'
  release: [
  revert: [
    '/^revert: (.*)/'

Shallow clones


Perform git fetch --shallow before linting.

Most likely you are reading this because you where presented with an error message:

  'Could not get git history from shallow clone.
  Use git fetch --shallow before linting.
  Original issue:\n Refer to for details.'


git supports checking out shallow clones of a repository to save bandwith in times. These limited copies do not contain a full git history. This makes conventional-changelog-lint fail, especially when running on large commit ranges. To ensure linting works every time you should convert a shallow git repo to a complete one. Use git fetch --shallow to do so.


Ensure full git checkouts on TravisCI, add to .travis.yml:

  - git fetch --unshallow


Ensure full git checkouts on AppVeyor, add to appveyor.yml:

shallow_clone: false

Supported Node.js versions

conventional-changelog-lint supports the active Node.js LTS version and higher: >= 4

Related projects

Copyright 2016 by Mario Nebl and contributors. Released under the MIT license.

Package Sidebar


npm i conventional-changelog-lint

Weekly Downloads






Last publish


  • marionebl