Get Started | Let's chat | Website

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
- Benefits using commitlint
Getting started
CLI
Config
Shared configuration
API
Tools
Version Support and Releases
Related projects
License
Development
- Install and run
- Publishing a release

What is commitlint

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.

Benefits using commitlint

Getting started

# 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

Add hook

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

CLI

Primary way to interact with commitlint.
npm install --save-dev @commitlint/cli
Packages: cli

Config

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 in package.json
Packages: cli, core
See Rules for a complete list of possible rules
An example configuration can be found at @commitlint/config-conventional

Shared configuration

A number of shared configurations are available to install and use with commitlint:

⚠️ If you want to publish your own shareable config then make sure it has a name aligning with the pattern commitlint-config-emoji-log or commitlint-config-your-config-name — then in extend all you have to write is emoji-log or your-config-name.

Documentation

Check the main website.

API

Alternative, programmatic way to interact with commitlint
Packages:
- format - Format commitlint reports
- lint - Lint a string against commitlint rules
- load - Load shared commitlint configuration
- read - Read commit messages from a specified range or last edit
See API for a complete list of methods and examples

Tools

Roadmap

Ideas: conventional-changelog/commitlint#94

commitlint is considered stable and is used in various projects as development tool.

We identify ease of adoption and developer experience as fields where there is room and need for improvement. The items on the roadmap should enhance commitlint regarding those aspects.

Adoption: Provide reusable Travis CI integration: @commitlint/travis-cli (https://github.com/conventional-changelog/commitlint/releases/tag/v5.1.0)
DX: Support PR squash scenario via ahmed-taj/commitlint-bot and @commitlint/travis-cli
Adoption: Make ahmed-taj/commitlint-bot configurable via commitlint configuration
Adoption: Create commitlint init
DX: Extend the configuration schema to allow for additional fields (descriptions, examples, fixes) on both the rule and value level
DX: Incorporate an extended version of lennym/commit-template deducing a template from commitlint configuration
DX: Rewrite @commitlint/prompt for better usability (might involve a lot of yak-shaving)

Version Support and Releases

Node.js LTS >= 14
git >= 2.13.2

Releases

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	End-of-life
v17	16.05.2022	16.05.2023	(till next main version)
v16	26.12.2021	26.12.2022
v15	17.11.2021	17.11.2022
v14	26.10.2021	26.10.2022
v13	24.05.2021	24.05.2022
v12	23.02.2021	23.02.2022
v11	13.09.2020	13.09.2020

Dates are subject to change.

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.

Related projects

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

License

Development

commitlint is developed in a mono repository.

Install and run

git clone [email protected]: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.

Package dependency overview

(Partly outdated)

Publishing a release

npm login
nvm use (if you have nvm installed)

nvm
asdf is supported as well

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.

Create Github release

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

Publish a `next` release (or i.e. patch release)

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>

Publishing (new) packages for the first time

npm publish [PACKAGE_NAME] --access public

From within the folder first i.e. cd @commitlint/new-packages.

Move `next` to `latest`

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>'

dasibcryptoidology / commitlint Goto Github PK

commitlint's Introduction