Awesome Open Source
Awesome Open Source

Get Started | Let's chat slack | 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

npm latest CircleCI

  • 🚓 Be a good commitizen
  • 📦 Share configuration via npm
  • 🤖 Tap into conventional-changelog

Contents


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

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 in your project npm install husky --save-dev or yarn add -D husky.

After that, you can create a .huskyrc file or add to your package.json the following code for

Husky V4:

{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

Husky V5

# .husky/commit-msg
# ...
npx --no-install commitlint --edit $1
# or
yarn commitlint --edit $1

Detailed Setup instructions

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.json, or .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:

⚠️ 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

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.

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

  • Node.js LTS >= 10.21.0
  • git >= 2.13.2

Related projects

License

Copyright by @marionebl. All commitlint packages are released under the MIT 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

commitlint-dependencies

Publishing a release

Before publishing a release do a yarn run publish --dry-run to get the upcoming version and update the version in the should print help test.
Commit that change before creating the new version without --dry-run.

npm login
yarn clean
yarn install
yarn run build
yarn test
yarn run publish --otp <one-time password>

Publish a next release

npm login
yarn clean
yarn install
yarn run build
yarn test
npx lerna publish --conventional-commits --dist-tag next --otp <one-time password>
Move next to latest
npm login

Move next to latest:

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

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
typescript (9,978) 
git (766) 
lint (94) 
conventions (26) 
commit (21) 

Find Open Source By Browsing 7,000 Topics Across 59 Categories

Advertising 📦 10
All Projects
Application Programming Interfaces 📦 124
Applications 📦 192
Artificial Intelligence 📦 78
Blockchain 📦 73
Build Tools 📦 113
Cloud Computing 📦 80
Code Quality 📦 28
Collaboration 📦 32
Command Line Interface 📦 49
Community 📦 83
Companies 📦 60
Compilers 📦 63
Computer Science 📦 80
Configuration Management 📦 42
Content Management 📦 175
Control Flow 📦 213
Data Formats 📦 78
Data Processing 📦 276
Data Storage 📦 135
Economics 📦 64
Frameworks 📦 215
Games 📦 129
Graphics 📦 110
Hardware 📦 152
Integrated Development Environments 📦 49
Learning Resources 📦 166
Legal 📦 29
Libraries 📦 129
Lists Of Projects 📦 22
Machine Learning 📦 347
Mapping 📦 64
Marketing 📦 15
Mathematics 📦 55
Media 📦 239
Messaging 📦 98
Networking 📦 315
Operating Systems 📦 89
Operations 📦 121
Package Managers 📦 55
Programming Languages 📦 245
Runtime Environments 📦 100
Science 📦 42
Security 📦 396
Social Media 📦 27
Software Architecture 📦 72
Software Development 📦 72
Software Performance 📦 58
Software Quality 📦 133
Text Editors 📦 49
Text Processing 📦 136
User Interface 📦 330
User Interface Components 📦 514
Version Control 📦 30
Virtualization 📦 71
Web Browsers 📦 42
Web Servers 📦 26
Web User Interface 📦 210