conventional-commit-hook

A pre-commit hook that validates commit messages against the Conventional Commits specification.

Features

• Validates commit message structure: type, optional scope, optional breaking marker, description
• Enforces all 11 standard Conventional Commit types out of the box
• Custom type overrides via --types
• Detects breaking changes from both the ! header marker and BREAKING CHANGE footer
• Strips git-generated comment lines and scissors line before validation
• Silent on success — writes only to stderr on failure, never to stdout
• Single runtime dependency: structlog

Installation

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/millsks/conventional-commit-hook
    rev: v0.1.0
    hooks:
      - id: conventional-commit-hook

Install the hook:

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

Usage

The hook runs automatically on git commit. It exits 0 (silent) on a valid message, or 1 (error to stderr) on an invalid one.

Supported commit types

Message format

<type>[(<scope>)][!]: <description>

[body]

[footer(s)]

• type — one of the 11 types above (lowercase)
• scope — optional, enclosed in parentheses: fix(auth): …
• ! — optional breaking change marker: feat!: …
• description — required, non-empty, starts immediately after :
• body — optional, separated from the header by a blank line
• footers — optional, each on its own line as Token: value or Token #value; BREAKING CHANGE: … marks a breaking release

Valid examples

feat: add user authentication
fix(auth): resolve null pointer on login
feat!: drop Python 2 support
feat(api)!: remove v1 endpoints
docs: update installation instructions

With body and footers:

feat: add OAuth2 support

Implements the PKCE flow with refresh token rotation.

BREAKING CHANGE: the /auth/token endpoint now requires a code_verifier
Reviewed-by: Alice <alice@example.com>

Invalid examples

# Missing type
Add user authentication

# Uppercase type
Feat: add something

# Missing space after colon
feat:add something

# No blank line before body
feat: add login
Body text without a blank line separator

Custom types

Override the allowed type set with --types:

    hooks:
      - id: conventional-commit-hook
        args: [--types, feat, fix, hotfix, chore]

When --types is supplied, only those types are accepted. Standard types not listed are rejected.

Development

See CONTRIBUTING.md for the full workflow.

Prerequisites

Pixi — all other dependencies are managed by Pixi.

Setup

git clone https://github.com/millsks/conventional-commit-hook
cd conventional-commit-hook
pixi run bootstrap

Common tasks

License

MIT — Copyright (c) 2026 Kevin Mills