commitcheck

commitcheck

Commit hygiene checker for a git repository's recent history. It reads the most recent 50 commits and checks subject length, placeholder subjects, DCO Signed-off-by trailers, malformed trailers, and whether each commit follows the message convention the repo itself actually uses. Every finding names the rule and the short sha of the commit it came from.

Install

npx @reneturcios/commitcheck check [path]

Or install it globally:

npm install -g @reneturcios/commitcheck

Requires Node 20 or newer and git on PATH.

CLI

commitcheck check [path] [--json]   # check a repo (default path: .)
commitcheck mcp                     # run the MCP server on stdio
commitcheck --version               # print the version

Exit codes: 0 when the verdict is CLEAN, 1 when it is FINDINGS, 2 for a usage error or an unreadable target, and 141 when the reader closed the output pipe early (the shell-visible equivalent of death by SIGPIPE).

Findings are printed in git log order, newest first, and the order is deterministic for a given history.

MCP

The MCP server exposes one tool:

• check_commits with argument path: runs the same check as the CLI and returns the full report as JSON.

Rules

Rule	Severity	What it means
SUBJECT-TOO-LONG	medium	The subject line is over 72 characters.
SUBJECT-VAGUE	low	The subject is empty or a placeholder such as wip, fix, update, changes, or .
NO-SIGNOFF	medium	The commit has no Signed-off-by trailer, in a repo whose history follows the DCO convention (see below).
CONVENTION-BREAK	low	The subject breaks the dominant message style of the range (see below).
MERGE-COMMIT	info	A merge commit, reported for context. Merge commits are never a finding above info.
TRAILER-MALFORMED	low	A Signed-off-by line without an email shape, for example Signed-off-by: Jane Doe with no <[email protected]>.

The verdict is CLEAN when the range has no medium findings, and FINDINGS otherwise. Low and info findings are reported but do not change the verdict.

The adaptive rules, stated plainly

commitcheck does not impose a house style. Both convention checks are learned from the range being checked:

• DCO / sign-off. A commit is flagged NO-SIGNOFF only when the repo demonstrably uses sign-off: at least half of the other commits in the range carry a well-formed Signed-off-by trailer. If the repo does not use sign-off, no commit is flagged for missing it. A malformed sign-off line does not count as a sign-off.
• Message convention. Two styles are tracked: conventional subjects (type: summary or type(scope): summary) and capitalized imperative subjects (Add the thing). When one style is used by at least 70 percent of the non-merge commits in the range, it is the dominant style, and a commit that breaks it is flagged CONVENTION-BREAK. When no style reaches 70 percent, nothing is flagged for style.

Limits

• Only the last 50 commits are checked.
• Style detection is statistical. A short or mixed history may have no dominant style, in which case no convention findings are produced.
• Sign-off presence is checked, not signature validity. commitcheck verifies that a Signed-off-by trailer with an email shape exists; it does not verify that the signer is the author or that any signature is genuine.
• Merge commits are detected from the Merge ... subject line, which is the default git shape; a hand-written subject that starts with Merge will be reported as one.