Lint commit messages

conventional-changelog-lint

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

Installation

Fetch it with npm

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

Usage

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

CLI

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

Recipes

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 github.com/other-name/test targeting master on github.com/your-name/test:

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

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

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
 
script:
  - ./scripts/lint:commit.sh # [1] scripts/lint:commit.sh

[1]: See scripts/lint:commit.sh for reference

API

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 {
  getPreset,
  getConfiguration
} from 'conventional-changelog-lint';
 
const report = lint(
  'docs: add node api interface usage',
  {
    preset: await getPreset('angular'),
    configuration: await readConfiguration('conventional-changelog-lint')
  }
);

Configuration

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

{
  "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

{
  "preset": "angular"
}

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

⇨ See conventional-changelog for details

rules

{
  "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

wildcards

Patterns to exclude from linting

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

Shallow clones

TL;DR

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: https://git.io/vyKMq\n Refer to https://git.io/vyKMv for details.'

Explanation

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.

Travis

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

before_install:
  - git fetch --unshallow

Appveyor

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

angular-precommit – Pre commit with angular conventions
conventional-changelog-cli – Generate a changelog from conventional commit history
cz-conventional-changelog-lint – Let an interactive command line interface help you with creating commit messages matching your conventional-changelog-lint configuration
conventional-changelog-lint-config-angular – Shareable conventional-changelog-lint config enforcing the angular commit convention
conventional-changelog-lint-config-atom – Shareable configuration for conventional-changelog-lint based on the atom commit guidelines
conventional-changelog-lint-config-patternplate – Lint your commits, patternplate-style
conventional-commits-detector – Detect what commit message convention your repository is using
conventional-github-releaser – Make a new GitHub release from git metadata
conventional-recommended-bump – Get a recommended version bump based on conventional commits
commitizen – Simple commit conventions for internet citizens
standard-changelog – Generate a changelog from conventional commit history, angular-style