commit-guard

commit-guard

Conventional commit linting with imperative mood detection.

$ commit-guard --range origin/main..HEAD
abc1234 feat: add user authentication
  ✓ all checks passed
def5678 wip: still working
  ✗ [subject] unknown type: wip
  ✗ [body] missing body

Install #

uv tool install git-commit-guard

Or via pre-commit.

Quick start #

# check HEAD
$ commit-guard

# check a specific commit
$ commit-guard abc1234

# check all commits in a PR range
$ commit-guard --range origin/main..HEAD

# read from a file (for git hooks)
$ commit-guard --message-file .git/COMMIT_EDITMSG

Checks

All checks run by default. Enable or disable individually with --enable / --disable:

Check What it verifies
subject Format matches type(scope): description, valid type, lowercase start, no trailing period, max 72 chars
imperative First word is an imperative verb — uses NLP, not just a regex
body Body is present after a blank line
signed-off Signed-off-by: trailer is present
signature GPG or SSH signature is valid

Configuration #

Place .commit-guard.toml in your project root. CLI flags always take precedence over the config file. 

# .commit-guard.toml
disable = ["signature", "body"]
scopes = ["auth", "api", "db"]
require-scope = true
types = ["feat", "fix", "chore", "wip"]
max-subject-length = 100
min-description-length = 10
require-trailers = ["Closes", "Reviewed-by"]

GitHub Actions #

Check all commits in a pull request:

jobs:
  lint-commits:
    runs-on: ubuntu-latest
    env:
      PR_BASE: ${{ github.event.pull_request.base.sha }}
      PR_HEAD: ${{ github.event.pull_request.head.sha }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: benner/commit-guard@v0.14.1
        with:
          range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
          disable: signed-off,signature

All inputs mirror the CLI flags: enable, disable, scopes, require-scope, types, max-subject-length, min-description-length, require-trailer, output-file.

pre-commit #

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/benner/commit-guard
    rev: v0.14.1
    hooks:
      - id: commit-guard
      - id: commit-guard-signature