git-commit-message-linter/README.md

Git Commit Message Linter

A Python CLI tool that validates git commit messages against configurable patterns including Conventional Commits and Angular conventions. Detects issues like short messages, missing scope, wrong tense, and provides smart fix suggestions. Integrates as a pre-commit hook with severity levels.

Features

• Pattern-based validation - Validate against Conventional Commits, Angular, or custom patterns
• Smart fix suggestions - Get actionable suggestions to fix validation errors
• Severity levels - Configure error, warning, and info levels for different rules
• Pre-commit hook integration - Works as a pre-commit framework hook
• Team configuration - Shareable YAML config file for team conventions
• Custom patterns - Define your own regex patterns for validation

Installation

Using pip

pip install git-commit-message-linter

From source

git clone https://github.com/example/git-commit-message-linter.git
cd git-commit-message-linter
pip install -e .

Quick Start

Validate a commit message

commit-linter validate "feat(auth): add user login"

Generate a configuration file

commit-linter init

Validate from a file

commit-linter validate -f commit.txt

Configuration

Create a .commit-linter.yaml file in your repository root:

style: conventional
min_length: 10
max_length: 100
line_max_length: 72
require_scope: false
allowed_types:
  - feat
  - fix
  - docs
  - style
  - refactor
  - test
  - chore
  - perf
  - ci
  - build
validators:
  length:
    enabled: true
    rules:
      subject_min_length:
        enabled: true
        severity: warning
      subject_max_length:
        enabled: true
        severity: warning
      line_max_length:
        enabled: true
        severity: info
  conventional:
    enabled: true
    rules:
      format:
        enabled: true
        severity: error
      type:
        enabled: true
        severity: error
      scope:
        enabled: true
        severity: warning
      subject_tense:
        enabled: true
        severity: warning

Available Rules

Length Validator

Rule	Description	Default Severity
subject_min_length	Subject line too short	warning
subject_max_length	Subject line too long	warning
body_min_length	Body too short	info
body_max_length	Body too long	warning
line_max_length	Line exceeds max length	info

Conventional Commit Validator

Rule	Description	Default Severity
format	Invalid format	error
type	Invalid type	error
scope	Missing scope (if required)	warning
subject_tense	Not imperative mood	warning
subject_capitalization	First letter capitalized	info
subject_period	Trailing period	info

Angular Commit Validator

Rule	Description	Default Severity
header_format	Invalid header format	error
type	Invalid type	error
scope	Missing scope	warning
header_line_length	Header exceeds 72 chars	warning
blank_line_after_header	Missing blank line	info
body_line_length	Body line exceeds 80 chars	info
footer_format	Invalid footer format	info

Pre-commit Hook Integration

Using pre-commit framework

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

- repo: https://github.com/example/git-commit-message-linter
  rev: v1.0.0
  hooks:
    - id: commit-linter
      stages: [commit-msg]

Using git hooks directly

Create .git/hooks/commit-msg:

#!/bin/bash
commit-linter hook $1

Make it executable:

chmod +x .git/hooks/commit-msg

Examples

Valid messages

feat(auth): add user login functionality
fix: handle null pointer exception
docs: update API documentation
refactor(core): improve performance
chore: update dependencies

Invalid messages with fixes

Invalid	Issue	Fix
added login	No type, past tense	feat: add login
Feature: add login	Wrong capitalization	feat: add login
fix: added error handling	Past tense	fix: add error handling
feat:	Missing description	feat: add login
a	Too short	feat: add login

CLI Commands

validate

Validate a commit message:

commit-linter validate "feat(auth): add login"
commit-linter validate -f commit.txt
commit-linter validate --severity error

hook

Run as git commit-msg hook:

commit-linter hook $1

init

Generate configuration template:

commit-linter init
commit-linter init -o .commit-linter.yaml --style conventional

list-rules

List all available rules:

commit-linter list-rules

check-git

Check if directory is a git repository:

commit-linter check-git

Custom Patterns

Add custom regex patterns to your config:

custom_patterns:
  - name: no_wip
    pattern: "^WIP:"
    message: "WIP commits should not be pushed"
    severity: error
    suggestion: "Remove WIP prefix or move to draft"
  - name: must_have_ticket
    pattern: "[A-Z]+-\d+"
    message: "Commit should reference a ticket"
    severity: warning
    suggestion: "Add ticket reference (e.g., PROJ-123)"
    inverse: true

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: pytest tests/
5. Run linting: flake8 commit_linter/ tests/
6. Submit a pull request

License

MIT License - see LICENSE file for details.