Metadata-Version: 2.4
Name: conventional-commit-hook
Version: 0.1.0
Summary: A pre-commit hook that enforces Conventional Commits standards on commit messages
Project-URL: Homepage, https://github.com/millsks/conventional-commit-hook
Project-URL: Issues, https://github.com/millsks/conventional-commit-hook/issues
Project-URL: Documentation, https://github.com/millsks/conventional-commit-hook#readme
Author-email: Kevin Mills <millsks@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Kevin Mills
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: commit-messages,conventional-commits,git-hooks,pre-commit
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control
Requires-Python: >=3.10
Requires-Dist: structlog>=24.0.0
Description-Content-Type: text/markdown

# conventional-commit-hook

[![CI](https://github.com/millsks/conventional-commit-hook/actions/workflows/ci.yml/badge.svg)](https://github.com/millsks/conventional-commit-hook/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/millsks/conventional-commit-hook/branch/main/graph/badge.svg)](https://codecov.io/gh/millsks/conventional-commit-hook)
[![PyPI](https://img.shields.io/pypi/v/conventional-commit-hook.svg)](https://pypi.org/project/conventional-commit-hook/)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/conventional-commit-hook.svg)](https://anaconda.org/conda-forge/conventional-commit-hook)
[![Python](https://img.shields.io/pypi/pyversions/conventional-commit-hook.svg)](https://pypi.org/project/conventional-commit-hook/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A [pre-commit](https://pre-commit.com/) hook that validates commit messages against the [Conventional Commits](https://www.conventionalcommits.org/) 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](https://www.structlog.org/)

## Installation

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

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

Install the hook:

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

| Type | Purpose |
|---|---|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting, no logic change |
| `refactor` | Code restructure, no feature or fix |
| `perf` | Performance improvement |
| `test` | Adding or fixing tests |
| `build` | Build system or dependency changes |
| `ci` | CI configuration changes |
| `chore` | Maintenance tasks |
| `revert` | Revert a previous commit |

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

```yaml
    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](CONTRIBUTING.md) for the full workflow.

### Prerequisites

[Pixi](https://pixi.sh) — all other dependencies are managed by Pixi.

### Setup

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

### Common tasks

| Command | Purpose |
|---|---|
| `pixi run test` | Unit tests only (fast inner loop) |
| `pixi run test-integration` | Integration tests |
| `pixi run cov` | Full suite + coverage gate (≥90%) |
| `pixi run fmt` | Auto-format with ruff |
| `pixi run lint` | Lint with ruff |
| `pixi run check` | Type-check with mypy (strict) |
| `pixi run build` | Build wheel + sdist |
| `pixi run ci` | Full CI gate — must pass before committing |

## License

[MIT](LICENSE) — Copyright (c) 2026 Kevin Mills
