CommitLens lints your unpushed conventional commits, previews the release notes they'll produce, and flags breaking changes — before they hit main.
$ commitlens check commitlens · origin/main..HEAD · feature/api ✗ totally rewrote the auth layer error type-empty: commit does not follow Conventional Commits ✗ fix(api): handle empty body. warn subject-full-stop: subject must not end with a period ✓ feat(api): add pagination 3 commits · 1 clean · 1 warning · 1 error · 1 breaking $ commitlens notes --range origin/main..HEAD ### ⚠ BREAKING CHANGES - totally rewrote the auth layer — tokens are now opaque
The checks every conventional-commit team needs, run against exactly what you're about to push.
Type/scope/subject rules from the Conventional Commits spec plus length limits, all tunable per repo through one JSON config.
See the grouped markdown your push will generate — Features, Fixes, and everything else — straight from your history.
Detects both ! bangs and BREAKING CHANGE: footers, and nags until each one carries a migration note.
Drop two lines into commit-msg or pre-push. Exit codes do the enforcement — no daemon, no config framework.
No flag? It reviews upstream..HEAD, or since the last semver tag. It always inspects exactly what you're about to ship.
Pure Node built-ins. Installs in milliseconds, runs offline, adds no supply-chain surface to your project.
npm i -g @stealth-alpha/commitlens
Or use npx @stealth-alpha/commitlens without installing.
commitlens check
Lints every unpushed commit with clear rule names and exit codes CI can gate on.
commitlens notes
See the release notes your push produces, breaking changes on top.
commitlens init
Write a config: allowed types, lengths, and per-rule severities.
It covers the core conventional-commit linting most teams actually use, and adds what commitlint doesn't give you out of the box: release-notes preview and breaking-change reporting for the exact range you're pushing — as one zero-dependency binary.
Everything is built on Node 18+ built-ins. Your install pulls exactly one package and nothing else.
Two ways: a ! after the scope in the subject, or a BREAKING CHANGE:/BREAKING-CHANGE: footer in the body. Both are reported with their migration note when present.