coauthorcheck 0.4.0

Validate Co-authored-by trailers in commit messages.

coauthorcheck

Lightweight command-line validation for Co-authored-by commit trailers.

Table of Contents

• Usage
• pre-commit
• GitHub Actions
• CLI
• Installation
• Common CLI Workflows
• Configuration
• Development

Usage

coauthorcheck works in any Git repository, regardless of the project's language or build system. You can use coauthorcheck in one of these three ways:

• as a pre-commit commit-msg hook for immediate local feedback
• in GitHub Actions to validate branch or pull request commits before merge
• directly from CLI

pre-commit

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

repos:
  - repo: https://github.com/simoncraf/coauthorcheck
    rev: v0.4.0
    hooks:
      - id: coauthorcheck
        stages: [commit-msg]

Then install the hook:

pre-commit install --hook-type commit-msg

This is required because coauthorcheck validates the final commit message file, and commit-msg is the Git hook that receives that file.

GitHub Actions

Validate commits introduced by branch pushes:

name: Validate Co-authored-by trailers

on:
  push:
    branches:
      - "feature/**"
      - "feat/**"

jobs:
  validate-commits:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"

      - name: Install coauthorcheck
        run: pip install coauthorcheck==0.4.0

      - name: Validate branch commits
        run: coauthorcheck "origin/main..HEAD"

Validate commits introduced by a pull request:

name: Validate Co-authored-by trailers on PR

on:
  pull_request:
    branches:
      - main

jobs:
  validate-commits:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"

      - name: Install coauthorcheck
        run: pip install coauthorcheck==0.4.0

      - name: Validate PR commits
        run: coauthorcheck "origin/${{ github.base_ref }}..HEAD"

See docs/integrations.md for local hooks, JSON output, PR comments, and more workflow examples.

When validation fails, coauthorcheck also prints a suggested corrected trailer line. If multiple issues affect the same trailer, they are merged into one canonical fix suggestion.

CLI

coauthorcheck .git/COMMIT_EDITMSG
coauthorcheck HEAD
coauthorcheck HEAD~5..HEAD
coauthorcheck main..HEAD
coauthorcheck origin/main..HEAD

coauthorcheck --file .git/COMMIT_EDITMSG
coauthorcheck --commit HEAD
coauthorcheck --range HEAD~5..HEAD

Positional input is auto-detected in this order:

• values containing .. or ... are treated as commit ranges
• existing paths are treated as commit message files
• everything else is treated as a commit ref

Use the explicit flags when you want fully unambiguous scripting.

Check the installed CLI:

coauthorcheck --help

Installation

Install from PyPI:

pip install coauthorcheck

Or with uv:

uv tool install coauthorcheck

Or with pipx:

pipx install coauthorcheck

After installation, run:

coauthorcheck --help

Common CLI Workflows

Validate the commit message currently being edited:

coauthorcheck .git/COMMIT_EDITMSG

Validate only the commits introduced by your current branch compared with main:

coauthorcheck main..HEAD

Validate only the commits introduced by your branch compared with the remote default branch:

coauthorcheck origin/main..HEAD

Validate the last few commits on the current branch:

coauthorcheck HEAD~3..HEAD

Configuration

coauthorcheck supports repository-local configuration from either:

• pyproject.toml under [tool.coauthorcheck]
• .coauthorcheck.toml

Configuration is resolved in this order:

1. --config <path>
2. nearest .coauthorcheck.toml
3. nearest pyproject.toml with [tool.coauthorcheck]
4. built-in defaults

When config files are auto-discovered, coauthorcheck searches upward from the current working directory. This means running the tool from a nested folder in the repo still finds the repo-level config.

Example using pyproject.toml:

[tool.coauthorcheck.rules]
single_word_name = false
github_handle = true
incorrect_casing = true
invalid_format = true
malformed_email = true
missing_email = true
missing_name = true

Example using .coauthorcheck.toml:

[rules]
single_word_name = false
github_handle = false
incorrect_casing = true
invalid_format = true
malformed_email = true
missing_email = true
missing_name = true

Use an explicit config file with:

coauthorcheck --config .coauthorcheck.toml main..HEAD

Unknown rule names or non-boolean values are treated as configuration errors.

See docs/rules.md for a detailed explanation of each rule. See docs/integrations.md for pre-commit, GitHub Actions, JSON output, and PR comment examples. Use coauthorcheck --format json ... for machine-readable output in CI and automation. JSON issue objects also include a suggestion field when a corrected trailer can be proposed.

Development

Set up the local environment:

uv sync

Run the CLI from the project environment:

uv run coauthorcheck --help

Run the tool from another repository by changing into that repository first and then invoking the executable from this project:

cd /path/to/other-repo
/path/to/coauthorcheck/.venv/Scripts/coauthorcheck.exe main..HEAD

In Git Bash, use /c/... style paths:

/path/to/coauthorcheck/.venv/Scripts/coauthorcheck.exe main..HEAD

Run the test suite:

uv run pytest

Run the linter:

uv run ruff check .