Ultimate Commit Message Validator Inspector

Validates commit messages against Conventional Commits format and project-specific rules before allowing commits, ensuring a clean and parseable git history.

When to Use This Hook

Attach this hook when you need to:

• Enforce Conventional Commits format (type(scope): description) across all team members
• Validate commit message length, type prefixes, and scope values against allowed lists
• Enable automated changelog generation and semantic versioning from commit history

Consider alternatives when:

• Your team uses a different commit convention like Angular or custom format
• You prefer squash-merge workflows where individual commit messages do not matter

Quick Start

Configuration

Copy
name: ultimate-commit-message-validator-inspector
type: hook
trigger: PreToolUse
category: git-workflow

Example Trigger

Copy
# Hook triggers before a git commit command
git commit -m "feat: add new feature"
# Validator checks message format against rules

Example Output

Commit Message Validator
  Message: "feat(auth): add OAuth2 login flow"
  Type: feat .......................... VALID
  Scope: auth ......................... VALID (in allowed list)
  Description: "add OAuth2 login flow"
    Length: 22 chars (max: 72) ........ PASS
    Starts lowercase: yes ............. PASS
    No period at end: yes ............. PASS
Commit message validated successfully.

Core Concepts

Validation Rules Overview

Aspect	Details
Type Prefix	Must be one of: feat, fix, docs, style, refactor, test, chore, perf, ci, build
Scope	Optional parenthetical scope from allowed list
Subject Line	Max 72 characters, lowercase start, no trailing period
Body	Optional, separated by blank line, wrapped at 100 characters
Breaking Change	BREAKING CHANGE: footer or ! after type/scope

Validation Workflow

Commit Command Intercepted
          |
    Extract Message
          |
    Parse Type(Scope): Desc
          |
    ┌─────┼─────┬─────┐
    |     |     |     |
  Type  Scope  Desc  Body
  Valid? Valid? Valid? Valid?
    |     |     |     |
    └─────┼─────┴─────┘
          |
    All Valid?
     /       \
   Yes        No
    |          |
  ALLOW     BLOCK +
  Commit    Show Errors
            + Example

Configuration

Parameter	Type	Default	Description
allowed_types	string[]	["feat","fix","docs","style","refactor","test","chore"]	Valid commit type prefixes
allowed_scopes	string[]	[]	Valid scope values (empty = any scope allowed)
max_subject_length	number	72	Maximum characters for the subject line
require_scope	boolean	false	Make scope mandatory in commit messages
require_body	boolean	false	Require a commit body for non-trivial changes

Best Practices

1. Provide Fix Examples on Failure - When a commit message fails validation, show an example of a valid message based on the attempted content. This teaches the convention rather than just rejecting.

2. Start with Common Types Only - Begin with feat, fix, docs, chore, and refactor. Add specialized types like perf, ci, build only when the team needs them.

3. Allow Flexible Scopes Initially - Do not enforce a scope allowlist until your project's module boundaries are stable. Premature scope restrictions create friction without clear benefit.

4. Enforce Subject Length Strictly - The 72-character limit ensures commit messages display correctly in terminals, GitHub, and git log. This is the most impactful rule to enforce.

5. Enable Breaking Change Detection - Configure the validator to recognize BREAKING CHANGE: footers and ! markers. This enables automated major version bumps in semantic release pipelines.

Common Issues

1. Merge Commit Messages - Git auto-generates merge commit messages like "Merge branch 'feature' into main" that do not follow Conventional Commits. Add an exception for merge commit patterns.

2. Multi-Line Messages via -m Flag - The -m flag makes multi-line messages awkward. Support both -m single-line and editor-based multi-line messages in the validator.

3. Revert Commit Format - Git revert creates messages starting with "Revert" which may not match your type list. Add revert as a valid type or exempt revert commits from validation.