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

<!-- [![TravisCI][6]][7] -->

• 🚓 Be a good

  commitizen

• 📦 Share configuration via

  npm

• 🤖 Tap into

  conventional-changelog

Contents

• What is commitlint
  • Benefits using commitlint
• Getting started
• CLI
• Config
• Shared configuration
• API
• Tools
• Version Support and Releaes
• 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
• ci
• chore
• docs
• feat
• fix
• perf
• refactor
• revert
• style
• test

These can be modified by your own configuration.

Benefits using commitlint

• Why Use Conventional Commits?
• "The perks of committing with conventions" (Talk slides)

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

# 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-install commitlint --edit "$1"'

Check the husky documentation on how you can automatically have Git hooks enabled after install for different

yarn

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

  commitlint.config.js

  ,

  .commitlintrc.js

  ,

  .commitlintrc

  ,

  .commitlintrc.json

  ,

  .commitlintrc.yml

  file or a

  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

• @commitlint/config-angular
• @commitlint/config-conventional
• @commitlint/config-lerna-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 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

.

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

• commitizen adapter
• prompt

Roadmap

Ideas: conventional-changelog/commitlint#94

commitlint

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

• [x] 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

  >= 12

• 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 | | -------------------------------------------------------------------------------- | -------------- | ----------- | | 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. Therefor we can't promise that we will release patch versions for older releases in a timley 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

Copyright by @marionebl. All

commitlint

Development

commitlint

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

Before publishing a release do a

yarn run publish --dry-run

should print help

--dry-run

npm login
nvm use (if you have nvm installed)

yarn clean
yarn install
yarn build
yarn test
yarn run publish --otp 

Create Github release

1. Copy changelog entry for the new version
2. Create release for the new tag: https://github.com/conventional-changelog/commitlint/releases
3. Post in the commitlint Slack-channel

Publish a

next

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

If for some reason this stops in between, you can manually publish missing packages like this:

npm publish  --tag next --otp 

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 '

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 '