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

```bash
pip install git-commit-message-linter
```

### From source

```bash
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

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

### Generate a configuration file

```bash
commit-linter init
```

### Validate from a file

```bash
commit-linter validate -f commit.txt
```

## Configuration

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

```yaml
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`:

```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`:

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

Make it executable:
```bash
chmod +x .git/hooks/commit-msg
```

## Examples

### Valid messages

```text
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:

```bash
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:

```bash
commit-linter hook $1
```

### init

Generate configuration template:

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

### list-rules

List all available rules:

```bash
commit-linter list-rules
```

### check-git

Check if directory is a git repository:

```bash
commit-linter check-git
```

## Custom Patterns

Add custom regex patterns to your config:

```yaml
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.