conventional-pre-commit

4.4.0 verified Mon Apr 27 auth: no python

A pre-commit hook that validates commit messages against the Conventional Commits specification. Supports husky-style configuration and custom patterns. Version 4.4.0, actively maintained, released monthly.

pip install conventional-pre-commit

Common errors

error conventional-pre-commit: error: argument types: invalid choice: 'feat' (choose from 'feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert') ↓

cause Misspelled type or custom type not allowed by default.

fix

Use one of the allowed types or add --types 'type1,type2' to allow custom types.

error conventional-pre-commit: error: unrecognized arguments: --force-scope ↓

cause Typo or incorrect argument name.

fix

Use the correct argument: --force-scope (double dash). Check official docs.

Warnings

gotcha The hook only runs on commit-msg stage. If you use a different stage (e.g., pre-commit), it will not validate the message. ↓

fix Set stages: [commit-msg] in your hook config.

gotcha Arguments like --strict or --force-scope are passed via the args list in pre-commit config, not environment variables. ↓

fix Use args: [--strict] in the hook definition.

breaking In version 4.0.0, the default behavior changed from allowing short footers to requiring full Conventional Commits spec. Old configs may reject previously valid messages. ↓

fix Update commit messages to match spec or use --no-verify temporarily.

Install

pre-commit install --hook-type commit-msg

Quickstart

Minimal pre-commit config to validate commit messages.

# In .pre-commit-config.yaml
repos:
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v4.4.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]
        args: [] # optional: add --strict, --force-scope, etc.