commit-gauge

A lightweight Conventional Commits linter for git hooks and CI, with clear fix-up suggestions.

commit-gauge checks commit messages against Conventional Commits. It tells you what's wrong and also what to write instead. Fixed the Login bug. gets the suggestion fix: fix the Login bug, and feature(API): Added new endpoint. gets feat(api): add new endpoint. Use it as a commit-msg hook, on a single message, or on every commit in a pull request.

CLI, library and GitHub Action. Node.js 18+, zero runtime dependencies (commitlint needs dozens). By Louis Wright.

Features

• Inputs: --message, --edit (the commit-msg hook file), --file, --stdin, or a git range --from/--to. Merge, revert and release commits are skipped. An all-zero --from (a new branch push) lints just the head commit.
• Header rules: format, allowed types (with the closest match: feature → feat, bugfix → fix), lowercase type and scope, empty and allowed scopes, empty subject, trailing full stop, sentence case, imperative mood (added → add), and max length.
• Body/footer rules: blank lines before body and footer, BREAKING CHANGE: spelling, line length (URLs exempt), optional Signed-off-by and issue-reference requirements.
• History hygiene: fixup!/squash!/amend! and WIP commits are caught before merge.
• Hook installer: commit-gauge --install-hook writes .husky/commit-msg if Husky is set up, otherwise .git/hooks/commit-msg.
• Output: text, JSON, SARIF 2.1.0 and Markdown; --fail-on; exit codes 0/1/2; allowlist entries with expiry dates.

Parser, commitlint configs, PR titles and the prompt

import { parseCommit, releaseType } from 'commit-gauge/parser';   // or require('commit-gauge/parser')
parseCommit('feat(api)!: add tokens\n\nBREAKING CHANGE: keys removed');
// { type: 'feat', scopes: ['api'], breaking: true, breakingNotes: ['keys removed'], footers: [...], ... }

• Switching from commitlint? Keep your commitlint.config.js / .commitlintrc; commit-gauge reads it (including extends: ['@commitlint/config-conventional']).
• Squash merges: commit-gauge --pr-title "$TITLE" or, in a pull_request workflow, commit-gauge --github-pr (title + every commit).
• Presets: { "extends": "./commit-preset.json" } in .commit-gauge.json, where the preset lists types (with descriptions), scopes and lint options.
• Prompt: commit-gauge prompt --commit asks for type, scope, subject, body, breaking change and issues, then commits a valid message.

Module formats and types

Ships ESM and CommonJS (import and require both work, via exports), with TypeScript declarations generated from the source at build time. Tests run on Node 18/20/22 in GitHub Actions (test/), including require/import checks against the packed tarball; releases are published with npm provenance.

Rules

Rule	Default severity	What it catches
header-format	high	Header is not "type(scope): subject"
type-unknown	high	Type is not in the allowed list
subject-empty	high	Subject (or whole message) is empty
fixup-commit	high	fixup!/squash!/amend! commit left in the history
type-case	medium	Type is not lowercase
scope-empty	medium	Empty scope "()"
scope-not-allowed	medium	Scope is not in the allowed list (or is required)
header-max-length	medium	Header is too long
breaking-change-format	medium	Malformed BREAKING CHANGE footer
wip-commit	medium	Work-in-progress commit
missing-signoff	medium	No Signed-off-by trailer (requireSignoff)
subject-case	low	Subject starts with an uppercase letter
scope-case	low	Scope is not lowercase
subject-full-stop	low	Subject ends with a full stop
body-leading-blank	low	No blank line between header and body
footer-leading-blank	low	No blank line before the footer
missing-issue-ref	low	No issue reference (issuePattern)
subject-imperative	info	Subject is not in the imperative mood
body-max-line-length	info	Body line is too long
allowlist-expired	medium	Allowlist entry has expired
allowlist-unused	info	Allowlist entry matched nothing

Install and run

npm install --save-dev commit-gauge
npx commit-gauge --install-hook                 # lint every commit message locally
npx commit-gauge -m "feature(API): Added new endpoint."
npx commit-gauge --from origin/main --to HEAD   # every commit on this branch
git log -1 --format=%B | npx commit-gauge --stdin

Sample output

commit-gauge — commit message
1 commit(s) linted, 1 with problems

HIGH     type "feature" is not one of: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert [type-unknown]
         ↳ fix: Use "feat". Suggested header: "feat(api): add new endpoint"
LOW      scope "API" should be lowercase [scope-case]
         ↳ fix: Use "api".
LOW      subject ends with a full stop [subject-full-stop]
         ↳ fix: Remove the trailing ".".
LOW      subject starts with an uppercase letter ("Added") [subject-case]
         ↳ fix: Use "added".

1 high, 3 low, 1 info
✖ Failing (fail-on: high).

Options

commit-gauge 1.0.0 — lint commit messages against Conventional Commits, with fix-up suggestions

Usage: commit-gauge [dir] [--message <msg> | --edit [file] | --file <file> | --stdin | --from <ref> --to <ref>] [options]
       commit-gauge --install-hook [--force]

Input (default: the last commit)
  -m, --message <msg>       Lint this message
  -e, --edit [file]         Lint the commit-msg hook file (default: .git/COMMIT_EDITMSG)
      --file <file>         Lint a message stored in a file
      --stdin               Read the message from stdin
      --from <ref>          Lint every commit in <from>..<to> (all-zero SHA = only <to>)
      --to <ref>            End of the range (default: HEAD)
Rules
      --types <list>        Allowed types (default: feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert)
      --scopes <list>       Allowed scopes (default: any)
      --require-scope       A scope is mandatory
      --max-length <n>      Header max length (default: 100)
      --require-signoff     Require a Signed-off-by trailer
      --issue-pattern <re>  Require an issue reference matching this regex
      --no-merges-ignored   Also lint merge commits
Hooks
      --install-hook        Write a commit-msg hook (.husky/commit-msg if husky is set up, else .git/hooks)

Common
  -c, --config <file>     JSON config (default: .commit-gauge.json or "commitGauge" in package.json)
  -f, --format <fmt>      text (default) | json | sarif | markdown
      --json <file>       Also write a JSON report
      --sarif <file>      Also write SARIF 2.1.0
      --markdown <file>   Also write Markdown (e.g. for a job summary)
      --fail-on <sev>     critical | high | medium | low | info | none (default: high)
      --list-rules        Print rules and default severities
      --no-fixes          Hide fix suggestions in text output
      --no-color          Disable colours
  -v, --version / -h, --help

Exit codes: 0 = passed, 1 = findings at or above --fail-on, 2 = usage, config or read error.

Configuration and allowlist

Options can live in .commit-gauge.json (or a "commitGauge" key in package.json, or --config <file>):

{
  "failOn": "medium",
  "severity": { "subject-case": "low" },
  "allowlist": [
    { "rule": "header-max-length", "subject": "3f2a9c1*", "reason": "Historic commit, cannot be rewritten", "expires": "2027-03-31" }
  ],
  "types": ["feat", "fix", "docs", "chore", "refactor", "perf", "test", "build", "ci", "revert", "deps"],
  "scopes": ["cli", "core", "action"],
  "headerMaxLength": 72,
  "requireSignoff": false,
  "issuePattern": "#\\d+|[A-Z]+-\\d+"
}

• severity changes a rule's severity, or turns it "off".
• allowlist entries suppress matching findings. Each needs a reason and matches on any combination of rule, file, subject (globs with *) and match (a substring of the message). Add expires (YYYY-MM-DD) so the exception is time-boxed: once it lapses the finding comes back along with an allowlist-expired finding (medium). Entries that no longer match anything are reported as allowlist-unused (info).

Other config keys: requireScope, subjectCase ("lower" or "any"), bodyMaxLineLength, ignore (regexes for headers to skip), ignoreMerges, ignoreReverts.

Output and exit codes

• --format text (default), json, sarif (SARIF 2.1.0 for GitHub code scanning) or markdown (for job summaries and PR comments). --json, --sarif and --markdown write extra report files in the same run.
• --fail-on <severity> sets the threshold (critical, high, medium, low, info, none; default high).
• Exit codes: 0 passed, 1 findings at or above --fail-on, 2 usage, config or read error.

GitHub Action

permissions:
  contents: read
  security-events: write   # only needed for the SARIF upload
jobs:
  commit-gauge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
        with: { persist-credentials: false, fetch-depth: 0 }
      - uses: MrLouisWright/commit-gauge@v1
        with:
          fail-on: high
          sarif: commit-gauge.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with: { sarif_file: commit-gauge.sarif }

Input	Description	Default
path	Project directory	.
from	Base ref (default: PR base SHA or the push before SHA)	`${{ github.event.pull_request.base.sha
to	Head ref (default: HEAD)	HEAD
fail-on	Failure threshold	high
config	Config file path
sarif / json	Write SARIF / JSON report to this path
job-summary	Add the Markdown report to the job summary	true
args	Extra CLI arguments

The action runs the bundled CLI with Node 20; it has no dependencies to install. Pin it to a commit SHA if your policy requires it.

In pull requests the action lints base..head; on pushes it lints before..after. Use fetch-depth: 0 so the range is available.

Library

import { lintMessage } from 'commit-gauge';
const r = lintMessage('Fixed the login bug.');
r.findings[0].rule; // 'header-format'
r.suggestion;       // 'fix: fix the login bug'

Types are included.

Requirements

Node.js 18 or newer. Zero runtime dependencies.

Support

If this project is useful to you, you can support its development with a donation: Buy me a coffee. It helps keep these tools maintained, documented and free for everyone.

Credit (optional)

Free to use under MIT, no attribution required. If commit-gauge helps you, a link back is appreciated:

<a href="https://louiswright.co.uk">Built with commit-gauge by Louis Wright</a>

[![Built with commit-gauge by Louis Wright](https://img.shields.io/badge/built%20with-commit--gauge-blue)](https://louiswright.co.uk)

Licence

MIT © Louis Wright (Louis Wright)