marioneblLint 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 - 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-lintconfigurationconventional-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
Copyright 2016 by Mario Nebl and contributors. Released under the MIT license.