Lint commit messages
Demo generated with svg-term-cli
cat docs/assets/commitlint.json | svg-term --out docs/assets/commitlint.svg --frame --profile=Seti --height=20 --width=80
- 🚓 Be a good
commitizen
- 📦 Share configuration via
npm
- 🤖 Tap into
conventional-changelog
- What is commitlint
- Getting started
- CLI
- Config
- Shared configuration
- API
- Tools
- Version Support and Releases
- Related projects
- License
- Development
commitlint checks if your commit messages meet the conventional commit format.
In general the pattern mostly looks like this:
type(scope?): subject #scope is optional; multiple scopes are supported (current delimiter options: "/", "\" and ",")
Real world examples can look like this:
chore: run tests on travis ci
fix(server): send cors headers
feat(blog): add comment section
Common types according to commitlint-config-conventional (based on the Angular convention) can be:
- build
- chore
- ci
- docs
- feat
- fix
- perf
- refactor
- revert
- style
- test
These can be modified by your own configuration.
# Install commitlint cli and conventional config
npm install --save-dev @commitlint/{config-conventional,cli}
# For Windows:
npm install --save-dev @commitlint/config-conventional @commitlint/cli
# Configure commitlint to use conventional config
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
To lint commits before they are created you can use Husky's commit-msg
hook:
# Install Husky v6
npm install husky --save-dev
# or
yarn add husky --dev
# Activate hooks
npx husky install
# or
yarn husky install
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'
Or use installed package instead
npm pkg set scripts.commitlint="commitlint --edit"
npx husky add .husky/commit-msg 'npm run commitlint ${1}'
Check the husky documentation on how you can automatically have Git hooks enabled after install for different yarn
versions.
Detailed Setup instructions
- Local setup - Lint messages on commit with husky
- CI setup - Lint messages during CI builds
- Primary way to interact with commitlint.
npm install --save-dev @commitlint/cli
- Packages: cli
- Configuration is picked up from:
.commitlintrc
.commitlintrc.json
.commitlintrc.yaml
.commitlintrc.yml
.commitlintrc.js
.commitlintrc.cjs
.commitlintrc.ts
.commitlintrc.cts
commitlint.config.js
commitlint.config.cjs
commitlint.config.ts
commitlint.config.cts
commitlint
field inpackage.json
- Packages: cli, core
- See Rules for a complete list of possible rules
- An example configuration can be found at @commitlint/config-conventional
A number of shared configurations are available to install and use with commitlint
:
- @commitlint/config-angular
- @commitlint/config-conventional
- @commitlint/config-lerna-scopes
- @commitlint/config-nx-scopes
- @commitlint/config-patternplate
- conventional-changelog-lint-config-atom
- conventional-changelog-lint-config-canonical
- commitlint-config-jira
⚠️ If you want to publish your own shareable config then make sure it has a name aligning with the patterncommitlint-config-emoji-log
orcommitlint-config-your-config-name
— then in extend all you have to write isemoji-log
oryour-config-name
.
Check the main website.
- Alternative, programmatic way to interact with
commitlint
- Packages:
- See API for a complete list of methods and examples
commitlint
is considered stable and is used in various projects as development tool.
- Node.js LTS
>= 18
- git
>= 2.13.2
Security patches will be applied to versions which are not yet EOL.
Features will only be applied to the current main version.
Release | Inital release |
---|---|
v18 | 10/2023 |
v17 | 05/2022 |
v16 | 12/2021 |
v15 | 11/2021 |
v14 | 10/2021 |
v13 | 05/2021 |
v12 | 02/2021 |
v11 | 09/2020 |
EOL is usually after around a year.
We're not a sponsored OSS project. Therefore we can't promise that we will release patch versions for older releases in a timely manner.
If you are stuck on an older version and need a security patch we're happy if you can provide a PR.
- conventional-changelog Generate a changelog from conventional commit history
- commitizen Simple commit conventions for internet citizens
- create-semantic-module CLI for quickly integrating commitizen and commitlint in new or existing projects
Copyright by @marionebl. All commitlint
packages are released under the MIT license.
commitlint
is developed in a mono repository.
git clone git@github.com:conventional-changelog/commitlint.git
cd commitlint
yarn
yarn run build # run build tasks
yarn start # run tests, again on change
For more information on how to contribute please take a look at our contribution guide.
From the project root directory, use the following commands to run the test suite
yarn clean
yarn install
yarn build
yarn test
(Partly outdated)
npm login
nvm use (if you have nvm installed)
yarn clean
yarn install
yarn build
yarn test
yarn run publish --otp <one-time password>
If something in between fails (like a new packages was added and needs to be published for the
first time but you forgot) you can use lerna publish from-package
to publish anythign that
has not been published yet.
- Copy changelog entry for the new version
- Create release for the new tag: https://github.com/conventional-changelog/commitlint/releases
- Post in the commitlint Slack-channel
npm login
nvm use (if you have nvm installed)
yarn clean
yarn install
yarn build
yarn test
npx lerna publish --conventional-commits --dist-tag [`next` | `[PATCH_RELEASE_VERSION]`] --otp <one-time password>
If for some reason this stops in between, you can manually publish missing packages like this:
npm publish <package-name> --tag [`next` | `[PATCH_RELEASE_VERSION]`] --otp <one-time password>
npm publish [PACKAGE_NAME] --access public
From within the folder first i.e. cd @commitlint/new-packages
.
npm login
npx lerna exec --no-bail --no-private --no-sort --stream -- '[ -n "$(npm v . dist-tags.next)" ] && npm dist-tag add ${LERNA_PACKAGE_NAME}@$(npm v . dist-tags.next) latest --otp <one-time password>'
Remove next:
npx lerna exec --no-bail --no-private --no-sort --stream -- '[ -n "$(npm v . dist-tags.next)" ] && npm dist-tag rm ${LERNA_PACKAGE_NAME} next --otp <one-time password>'