Pre-flight Conventional Auditor

Validates commit messages against the Conventional Commits specification before commits execute, enforcing consistent message formatting across the team.

When to Use This Hook

Attach this hook when you need to:

• Enforce Conventional Commits format (feat:, fix:, chore:, etc.) on all commit messages before they are recorded in git history
• Validate commit message structure including type, scope, description, body, and footer according to the specification
• Prevent non-conforming commit messages from entering the repository to maintain clean changelogs and semantic versioning

Consider alternatives when:

• Your project uses a different commit message convention that is not compatible with the Conventional Commits specification
• You already use commitlint with husky in your git hooks and adding another validation layer would be redundant

Quick Start

Configuration

Copy
name: pre-flight-conventional-auditor
type: hook
trigger: PreToolUse
category: git

Example Trigger

Copy
git commit -m "feat(auth): add OAuth2 login support"
# Hook validates before commit executes:
# Conventional Audit: Validating commit message...

Example Output

Conventional Commit Audit:
Message: feat(auth): add OAuth2 login support
Type: feat (VALID - recognized type)
Scope: auth (VALID - matches project scope)
Description: add OAuth2 login support (VALID - lowercase, no period)
Breaking Change: No
Body: Not provided (optional)
Footer: Not provided (optional)
Format: Compliant with Conventional Commits 1.0.0
Decision: ALLOW

Core Concepts

Conventional Commits Overview

Aspect	Details
Specification	Conventional Commits 1.0.0 (conventionalcommits.org)
Required Parts	Type and description are required; scope, body, footer are optional
Valid Types	feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
Breaking Changes	Indicated by ! after type/scope or BREAKING CHANGE: footer
Trigger Point	PreToolUse on Bash commands matching git commit patterns
Block Behavior	Returns exit code 2 to prevent commit with non-conforming message

Audit Validation Workflow

PreToolUse (Bash with git commit)
    |
    v
[Extract commit message from -m flag]
    |
    v
[Parse: type(scope): description]
    |
    v
[Validate type against allowed list]
    |
    v
[Validate scope if present]
    |
    v
[Check description format (lowercase, no period)]
    |
    v
[Check for breaking change indicators]
    |
    v
[All valid?]
    |          |
   No         Yes
    |          |
 BLOCK       ALLOW
(exit 2)   (proceed)
    |
    v
[Output specific validation errors]

Configuration

Parameter	Type	Default	Description
allowed_types	string	feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert	Pipe-separated list of valid commit type prefixes
require_scope	boolean	false	Whether the scope component is required in commit messages
allowed_scopes	string	(any)	Pipe-separated list of valid scope values; empty allows any scope
max_description_length	integer	72	Maximum character length for the commit description line
enforce_lowercase_description	boolean	true	Whether the description must start with a lowercase letter

Best Practices

1. Align allowed types with your changelog generator - If you use a tool like conventional-changelog or semantic-release, configure the auditor's allowed_types to match the types your changelog tool recognizes. This ensures every commit message contributes to accurate release notes.

2. Define allowed scopes based on project modules - Use the allowed_scopes parameter to restrict scope values to your project's actual module names like auth, api, ui, or database. This prevents typos and maintains consistent scoping across team members.

3. Keep description lines under 72 characters - The default max_description_length of 72 characters follows git best practices for commit message display. Descriptions beyond this length are truncated in many git tools and GitHub interfaces.

4. Use the auditor alongside semantic versioning - Conventional Commits directly maps to semantic versioning: feat: triggers a minor version bump, fix: triggers a patch bump, and BREAKING CHANGE triggers a major bump. The auditor ensures your commits support automated versioning.

5. Train the team with clear error messages - When the auditor blocks a commit, the error output should explain exactly what is wrong and provide an example of a correct message. Good error messages accelerate team adoption of the convention.

Common Issues

1. Auditor blocks commits with multi-line messages - The hook parses the -m flag value for the commit message. Multi-line messages using multiple -m flags or heredoc syntax may not be parsed correctly. Use a single -m with the full first line for validation.

2. Scope validation rejects valid module names - If allowed_scopes is configured but does not include all project modules, valid scopes will be rejected. Keep the allowed scopes list updated as new modules are added to the project.

3. Hook does not fire for interactive commits - The auditor matches git commit -m in Bash commands. Interactive commits without the -m flag (which open an editor) are not intercepted because the message is not available in the command string. Use a git commit-msg hook for comprehensive coverage.