> Lint commit messages

# conventional-changelog-lint [![stability][0]][1]

[![npm version][6]][7] [![Travis branch][2]][3] [![AppVeyor branch][4]][5]

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

## Installation

Fetch it with `npm`

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

## Usage

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

### CLI

![conventional-changelog-lint demo](https://git.io/v2iTI)

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

```shell
❯ 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"](https://git.io/JDwyQg)

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


#### Last commit
As part of `npm test`

```json
  {
    "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`:

```sh
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`:

```sh
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](./scripts/lint:commit.sh#6) 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.

```yml
# 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](./scripts/lint:commit.sh) for reference

### API

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

```js
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:

```js
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](https://github.com/marionebl/conventional-changelog-lint-config-angular#rules)
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](#extends) configuration.

### extends

```js
{
  "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](https://www.npmjs.com/search?q=conventional-changelog-lint-config)
for available shareable configurations.

---

⇨ See [shareable-config](./documentation/shareable-config.md) for details

### preset

```js
{
  "preset": "angular"
}
```

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

---

⇨ See [conventional-changelog](https://github.com/ajoslin/conventional-changelog#preset)
for details

### rules

```js
{
  "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](https://github.com/marionebl/conventional-changelog-lint-config-angular),
which is loaded by default.

---

⇨ See [rules](./documentation/rules.md) for details

### wildcards

Patterns to exclude from linting

```js
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`:

```yml
before_install:
  - git fetch --unshallow
```

### Appveyor

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

```yml
shallow_clone: false
```

## Supported Node.js versions

conventional-changelog-lint supports the active Node.js [LTS](https://github.com/nodejs/LTS#lts-schedule) version and higher: `>= 4`

## Related projects

*   [angular-precommit](https://git.io/vwTDd)
– Pre commit with angular conventions

*   [conventional-changelog-cli](https://git.io/vwTDA)
– Generate a changelog from conventional commit history

*   [cz-conventional-changelog-lint](https://git.io/vwTyf)
– Let an interactive command line interface help you with creating commit
messages matching your `conventional-changelog-lint` configuration

*   [conventional-changelog-lint-config-angular](https://git.io/vwTy4)
– Shareable conventional-changelog-lint config enforcing the angular
commit convention

*   [conventional-changelog-lint-config-atom](https://git.io/vwTy9)
– Shareable configuration for conventional-changelog-lint based on the
atom commit guidelines

*   [conventional-changelog-lint-config-patternplate](https://git.io/vwTyz)
– Lint your commits, patternplate-style

*   [conventional-commits-detector](https://git.io/vwTyk)
– Detect what commit message convention your repository is using

*   [conventional-github-releaser](https://git.io/vwTyI)
– Make a new GitHub release from git metadata

*   [conventional-recommended-bump](https://git.io/vwTyL)
– Get a recommended version bump based on conventional commits

*   [commitizen](https://git.io/vwTym)
– Simple commit conventions for internet citizens

*   [standard-changelog](https://git.io/vwTyO)
– Generate a changelog from conventional commit history, angular-style

---

Copyright 2016 by [Mario Nebl](https://github.com/marionebl)
and [contributors](./graphs/contributors).
Released under the [MIT license]('./license.md').


[0]: https://img.shields.io/badge/stability-experimental-orange.svg?style=flat-square
[1]: https://nodejs.org/api/documentation.html#documentation_stability_index
[2]: https://img.shields.io/travis/marionebl/conventional-changelog-lint/master.svg?style=flat-square
[3]: https://travis-ci.org/marionebl/conventional-changelog-lint
[4]: https://img.shields.io/appveyor/ci/marionebl/conventional-changelog-lint/master.svg?style=flat-square
[5]: https://ci.appveyor.com/project/marionebl/conventional-changelog-lint
[6]: https://img.shields.io/npm/v/conventional-changelog-lint.svg?style=flat-square
[7]: https://npmjs.org/package/conventional-changelog-lint