committing-with-commitlint

Committing in a repository that uses commitlint

commitlint validates commit messages against the repository's configured convention (usually Conventional Commits). The configuration is the contract: read it before writing a commit message, and trust the error output when a commit is rejected.

1. Detect whether the repository uses commitlint

Any of these means commitlint is in play:

• A config file in the repository root: .commitlintrc, .commitlintrc.{json,yaml,yml,js,cjs,mjs,ts,cts,mts}, or commitlint.config.{js,cjs,mjs,ts,cts,mts}
• A "commitlint" field in package.json
• A commit-msg hook that runs commitlint (check .husky/commit-msg, lefthook.yml, or .git/hooks/commit-msg)

2. Read the enforced rules

npx commitlint --print-config json

If this exits non-zero, the configuration itself is broken (for example an unresolvable extends) — read the error on stderr instead of guessing.

Look at the rules object. Each rule is [severity, applicability, value]:

• severity — 0 = disabled, 1 = warning, 2 = error (only errors block commits)
• applicability — "always" = the condition must hold, "never" = it must not
• value — the rule's parameter (list, number, or string)

The rules that matter most when writing a message:

Rule	What it controls
type-enum	Allowed types (e.g. feat, fix, chore, ...)
scope-enum	Allowed scopes (empty list = any scope allowed)
scope-empty	[2, "never"] = scope is required; [2, "always"] = scope is forbidden
subject-case	With "never": cases the subject must NOT use
subject-full-stop	With "never" and ".": subject must not end with a period
header-max-length	Maximum length of the first line
body-leading-blank	Blank line required between subject and body
body-max-line-length	Maximum length of each body line

A rule that is absent or disabled (severity 0) is simply not enforced. When unsure, use a conservative baseline that passes the common presets: lower-case type, no trailing period, header under 72 characters (config-conventional allows up to 100). Note that running commitlint with no config at all fails with an empty-rules error rather than falling back to any default convention.

3. Write the message

Format: type(scope): subject — the scope is optional unless scope-empty is [2, "never"].

An example that satisfies @commitlint/config-conventional:

feat(parser): add support for inline issue references

Explain what changed and why. Separate the body from the subject with a blank
line (body-leading-blank) and keep lines within body-max-line-length.

Closes #123

4. Validate before committing

printf '%s' "feat(parser): add support for inline issue references

Explain what changed and why.

Closes #123" | npx commitlint

Exit code 0 with no output means the message passes. Validate the complete message (header and body), not just the first line — body rules are checked too. Doing this before committing is cheaper than a failed commit.

5. Self-correct when the commit-msg hook rejects

Rejection output names each violated rule in brackets:

⧗   --- input ---
Feat: Added new parser.
✖   subject must not be sentence-case, start-case, pascal-case, upper-case [subject-case]
✖   subject may not end with full stop [subject-full-stop]
✖   type must be lower-case [type-case]
✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]

✖   found 4 problems, 0 warnings

• Fix ONLY the rules named in brackets; keep everything else identical.
• Re-validate via stdin (step 4), then retry the commit.
• NEVER bypass the hook with git commit --no-verify — fixing the message is always the correct action.