# Commitlint — Lint Commit Messages to Enforce Conventions

> Commitlint checks that your Git commit messages meet the Conventional Commits standard so your project history stays clean and automated tooling like changelogs and version bumps works reliably.

## Install

Save as a script file and run:

# Commitlint — Lint Commit Messages to Enforce Conventions

## Quick Use
```bash
npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
echo "npx --no -- commitlint --edit $1" > .husky/commit-msg
```

## Introduction
Commitlint is a linting tool for Git commit messages. It validates every commit against configurable rules, most commonly the Conventional Commits specification. By catching malformed messages at commit time, Commitlint ensures that your Git history is structured enough for automated changelog generation, semantic versioning, and meaningful release notes.

## What Commitlint Does
- Validates commit messages against a configurable set of rules at commit time
- Enforces the Conventional Commits format (type, scope, subject, body, footer)
- Integrates with Husky or other Git hook managers to run on every commit
- Provides clear error messages showing exactly which rules a commit message violates
- Supports custom and shared configurations for team-wide consistency

## Architecture Overview
Commitlint parses each commit message into structured parts (type, scope, subject, body, footer) using a parser based on the conventional-changelog ecosystem. It then runs the parsed result through a set of rules defined in the configuration file. Each rule can be set to warning or error level with configurable parameters. The tool reads configuration from `commitlint.config.js`, `.commitlintrc`, or the `commitlint` field in `package.json`.

## Self-Hosting & Configuration
- Install the CLI and a config preset with `npm install --save-dev @commitlint/cli @commitlint/config-conventional`
- Create `commitlint.config.js` extending `@commitlint/config-conventional` for standard rules
- Wire into Husky by adding a `commit-msg` hook that runs `commitlint --edit $1`
- Customize individual rules by overriding them in your config file (e.g., max header length)
- Use `@commitlint/config-angular` or create a custom shared config for non-standard conventions

## Key Features
- Supports the full Conventional Commits specification including breaking change footers
- Shareable configuration packages let teams publish and reuse commit rules across repositories
- Plugin system for adding custom rules beyond the built-in set
- CLI can lint a range of commits for retroactive checks in CI pipelines
- Prompt CLI (`@commitlint/prompt-cli`) guides developers through writing valid messages interactively

## Comparison with Similar Tools
- **Commitizen** — Guides developers through writing commits via prompts; Commitlint validates after the fact
- **semantic-release** — Reads Conventional Commits for versioning; Commitlint enforces the format that semantic-release depends on
- **git-cliff** — Generates changelogs from structured commits; does not enforce commit formats
- **Husky** — Runs Git hooks; Commitlint is the linting tool that Husky triggers on the commit-msg hook
- **Conventional Changelog** — Generates changelogs from commit history; Commitlint ensures commits follow the expected format

## FAQ
**Q: What is a valid Conventional Commit message?**
A: The format is `type(scope): subject` where type is feat, fix, chore, docs, etc. Scope is optional. Example: `feat(auth): add OAuth2 login flow`.

**Q: Can I use Commitlint without Husky?**
A: Yes. You can run Commitlint in CI against a range of commits using `commitlint --from HEAD~5` or integrate it with any Git hook manager.

**Q: Does Commitlint work with monorepos?**
A: Yes. You can enforce scope rules that match package names and share a single Commitlint config at the repository root.

**Q: Can I allow custom commit types beyond the standard set?**
A: Yes. Override the `type-enum` rule in your config to add custom types like `build`, `perf`, `ci`, or any identifier your team uses.

## Sources
- https://github.com/conventional-changelog/commitlint
- https://commitlint.js.org

---
Source: https://tokrepo.com/en/workflows/cb946f21-3bec-11f1-9bc6-00163e2b0d79
Author: Script Depot