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

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

❯ conventional-changelog-lint --help
  conventional-changelog-lint@0.1.0 - 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

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')
  }
);

Recipes

As a commitmsg git-hook with "husky"

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

As part of npm test

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

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: (.*)/'
  ]
}

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

whizark/conventional-changelog-lint