Conventional Commit Linter

What Conventional Commits actually requires

Conventional Commits is a lightweight convention for commit messages that makes history machine-readable. The core rule is simple: every commit header is type(scope): subject, where the scope is optional. From that one pattern, tools can auto-generate changelogs, decide semantic version bumps, and group changes by area. This linter parses your message in your browser, checks it against the spec rule by rule, and hands you a corrected version you can copy straight back into git.

Nothing you paste leaves your machine. The parsing and validation are pure client-side JavaScript, so it works offline and never logs your commits.

The valid types

• feat - a new feature (triggers a minor version bump under SemVer).
• fix - a bug fix (triggers a patch version bump).
• docs - documentation-only changes.
• style - formatting, whitespace, semicolons; no code-behavior change.
• refactor - a code change that neither fixes a bug nor adds a feature.
• perf - a change that improves performance.
• test - adding or correcting tests.
• build, ci, chore, revert - build system, CI config, maintenance, and reverts respectively.

The rules this linter enforces

1. A type is present before the colon, and it is one of the recognized types.
2. The header matches type(scope): subject, with a colon and a space before the subject.
3. The subject is not empty and does not end with a period.
4. The header line is 72 characters or fewer so it renders cleanly in git log, GitHub, and email.
5. If there is a body, a blank line separates it from the header.

Why the imperative mood

The widely-followed convention is to write subjects in the imperative mood: 'add login page', not 'added login page' or 'adds login page'. The reasoning is that a commit message completes the sentence 'If applied, this commit will...'. 'If applied, this commit will add login page' reads correctly; 'will added login page' does not. The linter flags past-tense starters as a style note and rewrites them in the suggested fix. This is a strong convention rather than a hard spec requirement, so it appears as a warning, not a failure.

Why teams bother with this

Consistent commit messages are not busywork - they unlock automation. Tools like semantic-release read your types and decide whether the next version is a patch, minor, or major bump, with zero human judgment. Changelog generators group feat and fix commits into readable release notes automatically. Even without automation, a history where every line starts with a clear type is dramatically faster to scan when you are hunting for when a bug was introduced.

Getting Claude Code to write compliant commits

Claude Code writes commit messages for you, and it follows Conventional Commits well when you ask it to. Put a line in your CLAUDE.md like 'always write commit messages in Conventional Commits format (type(scope): subject), imperative mood, 72-char header'. Then let it draft the message and paste the result here to double-check before you commit. Over time you will barely need the linter - but it is the fast way to verify a message and to teach yourself the pattern until it is automatic.