Top Related Projects
Git hooks made easy 🐶 woof!
The commitizen command line utility. #BlackLivesMatter
:package::rocket: Fully automated version management and package publishing
:dragon: Lerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository.
Create committing rules for projects :rocket: auto bump versions :arrow_up: and auto changelog generation :open_file_folder:
Quick Overview
Commitlint is a tool that helps enforce consistent commit message conventions in Git repositories. It checks commit messages against predefined rules, ensuring that they follow a specific format or contain required information. This helps maintain a clean and standardized commit history, making it easier to generate changelogs and understand project evolution.
Pros
- Enforces consistent commit message formatting across a project or team
- Integrates easily with popular development tools and CI/CD pipelines
- Highly configurable, allowing for custom rules and conventions
- Improves the overall quality of commit history, making it easier to track changes and generate changelogs
Cons
- Can be seen as restrictive or overly rigid by some developers
- Requires initial setup and configuration, which may take time
- May cause friction in the development process, especially for teams not used to following strict commit conventions
- Some developers might find it challenging to adapt to the required commit message format
Code Examples
- Basic configuration (commitlint.config.js):
module.exports = {
extends: ['@commitlint/config-conventional']
};
This example sets up commitlint to use the conventional commit format.
- Custom rule configuration:
module.exports = {
rules: {
'header-max-length': [2, 'always', 72],
'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']]
}
};
This example defines custom rules for commit message header length and allowed commit types.
- Using commitlint with Husky:
{
"husky": {
"hooks": {
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
}
}
This example shows how to integrate commitlint with Husky to run checks on commit messages.
Getting Started
To get started with commitlint:
-
Install commitlint and its conventional config:
npm install --save-dev @commitlint/cli @commitlint/config-conventional
-
Create a commitlint configuration file:
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
-
Install Husky to run commitlint on commit messages:
npm install --save-dev husky npx husky install npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'
Now, commitlint will check your commit messages against the conventional commit format.
Competitor Comparisons
Git hooks made easy 🐶 woof!
Pros of husky
- More versatile, allowing for various Git hooks beyond just commit message linting
- Easier to set up and configure for multiple hooks
- Supports custom scripts and commands for each hook
Cons of husky
- Not specifically designed for commit message linting, requiring additional setup for this purpose
- May introduce more complexity when only commit message linting is needed
- Requires more configuration for commit message validation compared to commitlint
Code comparison
husky configuration in package.json:
{
"husky": {
"hooks": {
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
}
}
commitlint configuration in package.json:
{
"commitlint": {
"extends": ["@commitlint/config-conventional"]
}
}
Summary
husky is a more general-purpose tool for managing Git hooks, offering flexibility and support for various pre-commit and pre-push tasks. commitlint, on the other hand, is specifically designed for commit message linting and follows conventional commit standards out of the box. While husky can be configured to work with commitlint, it requires additional setup compared to using commitlint alone. The choice between the two depends on whether you need a more comprehensive Git hooks solution or a focused commit message linting tool.
The commitizen command line utility. #BlackLivesMatter
Pros of cz-cli
- Interactive CLI prompts for easier commit message creation
- Customizable commit types and scopes
- Supports plugins for extended functionality
Cons of cz-cli
- Requires additional setup and configuration
- May slow down the commit process for experienced users
- Less strict enforcement of commit message format
Code Comparison
cz-cli:
module.exports = {
types: [
{ value: 'feat', name: 'feat: A new feature' },
{ value: 'fix', name: 'fix: A bug fix' },
// ...
],
scopes: [{ name: 'accounts' }, { name: 'admin' }, { name: 'exampleScope' }],
// ...
};
commitlint:
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']],
'scope-enum': [2, 'always', ['accounts', 'admin', 'exampleScope']],
},
};
Summary
cz-cli offers an interactive approach to creating commit messages, making it easier for developers to follow conventions. It's highly customizable but requires more setup. commitlint, on the other hand, focuses on enforcing commit message rules and integrates well with CI/CD pipelines. While cz-cli guides users through the commit process, commitlint validates messages against predefined rules.
:package::rocket: Fully automated version management and package publishing
Pros of semantic-release
- Automates the entire package release workflow, including version bumping and changelog generation
- Integrates seamlessly with CI/CD pipelines for fully automated releases
- Supports multiple release strategies and customizable plugins
Cons of semantic-release
- Requires more initial setup and configuration compared to commitlint
- May be overkill for smaller projects or those with infrequent releases
- Less flexible for projects with non-standard versioning schemes
Code Comparison
semantic-release configuration:
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/npm",
"@semantic-release/github"
]
}
commitlint configuration:
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']]
}
};
Summary
While commitlint focuses on enforcing commit message conventions, semantic-release provides a comprehensive solution for automating the entire release process. semantic-release is more powerful but requires more setup, while commitlint is simpler and more focused on maintaining consistent commit messages. The choice between the two depends on project size, release frequency, and desired level of automation.
:dragon: Lerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository.
Pros of Lerna
- Manages multiple packages within a single repository (monorepo)
- Automates versioning and publishing of packages
- Optimizes dependency management across packages
Cons of Lerna
- Steeper learning curve for complex monorepo setups
- Less focused on commit message formatting and validation
- May introduce overhead for smaller projects
Code Comparison
Lerna (lerna.json):
{
"version": "independent",
"npmClient": "npm",
"command": {
"publish": {
"ignoreChanges": ["*.md"]
}
}
}
Commitlint (.commitlintrc.js):
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']]
}
};
Key Differences
- Lerna focuses on monorepo management and package publishing
- Commitlint specializes in enforcing commit message conventions
- Lerna is more suitable for large-scale projects with multiple packages
- Commitlint is ideal for maintaining consistent commit history across any project size
Use Cases
- Use Lerna for managing complex monorepos with multiple packages
- Use Commitlint for enforcing consistent commit messages and improving changelog generation
- Consider using both tools together for comprehensive project management and version control
Create committing rules for projects :rocket: auto bump versions :arrow_up: and auto changelog generation :open_file_folder:
Pros of Commitizen
- Provides an interactive CLI tool for creating standardized commit messages
- Supports multiple commit message conventions and allows custom configurations
- Offers automatic versioning and changelog generation based on commit messages
Cons of Commitizen
- Requires Python installation, which may not be ideal for all projects
- Learning curve for team members unfamiliar with the tool
- May introduce additional complexity in the development workflow
Code Comparison
Commitlint configuration (.commitlintrc.js
):
module.exports = {
extends: ['@commitlint/config-conventional']
};
Commitizen configuration (pyproject.toml
):
[tool.commitizen]
name = "cz_conventional_commits"
version = "0.1.0"
tag_format = "v$version"
Both tools aim to standardize commit messages, but they approach the task differently. Commitlint focuses on linting commit messages against predefined rules, while Commitizen provides an interactive interface for creating compliant commits.
Commitlint is typically used as a pre-commit hook to enforce commit message standards, whereas Commitizen guides developers through the commit process, potentially reducing errors and inconsistencies.
While Commitlint is more lightweight and easier to integrate into existing JavaScript projects, Commitizen offers a more comprehensive solution with additional features like versioning and changelog generation.
The choice between these tools depends on project requirements, team preferences, and existing technology stack. Some projects may even use both tools in conjunction for a more robust commit message workflow.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Get Started | Website
Lint commit messages
Demo generated with svg-term-cli
cat docs/assets/commitlint.json | svg-term --out docs/public/assets/commitlint.svg --frame --profile=Seti --height=20 --width=80
- ð 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
- chore
- ci
- docs
- feat
- fix
- perf
- refactor
- revert
- style
- test
These can be modified by your own configuration.
Benefits of using commitlint
Getting started
- 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.mjs
.commitlintrc.ts
.commitlintrc.cts
commitlint.config.js
commitlint.config.cjs
commitlint.config.mjs
commitlint.config.ts
commitlint.config.cts
commitlint
field inpackage.json
commitlint
field inpackage.yaml
- 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-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 pattern
commitlint-config-emoji-log
orcommitlint-config-your-config-name
â then in extend all you have to write isemoji-log
oryour-config-name
.
Documentation
Check the main website.
API
- Alternative, programmatic way to interact with
commitlint
- Packages:
- See API for a complete list of methods and examples
Tools
Roadmap
commitlint
is considered stable and is used in various projects as a development tool.
Version Support and Releases
- Node.js LTS
>= 18
- 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 | Initial release |
---|---|
v19 | 02/2024 |
v18 | 10/2023 |
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.
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
packages are released under the MIT license.
Development
commitlint
is developed in a mono repository.
Install and run
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
yarn run commitlint # run CLI
For more information on how to contribute please take a look at our contribution guide.
Top Related Projects
Git hooks made easy 🐶 woof!
The commitizen command line utility. #BlackLivesMatter
:package::rocket: Fully automated version management and package publishing
:dragon: Lerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository.
Create committing rules for projects :rocket: auto bump versions :arrow_up: and auto changelog generation :open_file_folder:
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot