Lint My Headers

Fast copyright and license header checks, powered by Rust.
One policy for your codebase. Clear findings. Small, reviewable repairs.

Documentation · Quick start · Integrations · Releases

Keep copyright and license notices consistent across your codebase, and turn an annual refresh into a small diff. Run lmh locally, in CI, or from a coding agent using the same explicit policy.

Highlights

• Native Rust execution. A compiled CLI with no Python, Node.js, or language toolchain required to run the installed binary.
• Nine languages, one policy. Python, JavaScript, TypeScript, Rust, Go, Swift, Bash, C, and C++.
• Leading-header checks. Recognizes the opening comment region and requires notices before code, keeping header-like text in program bodies out of repairs.
• Precise, reviewable fixes. Refreshes recognized stale years while preserving the creation year, owner, all other bytes, and file permissions.
• Fits your workflow. First-party pre-commit/prek hook, GitHub Action, and stable JSON diagnostics for scripts and coding agents.

Performance

On 10,000 mixed-language files (1 KiB/file), the release CLI measured:

Five timing trials after warmup on the same shared Linux runner. Both tools receive the same CPU budget; LMH uses up to four available workers for large trees.

See the performance guide for repair time, peak memory, all nine languages, CSVs, methodology and reproduction. These are synthetic, warm-cache results; CPU limits and storage affect the comparison.

Installation

Install the published release with uv:

uv tool install lint-my-headers==0.7.0

Or install with pip: python -m pip install lint-my-headers==0.7.0.

Version 0.7.0 supports all nine languages and policy in .lmh.toml, pyproject.toml, Cargo.toml, or package.json. Select your project's languages in the policy; the default remains Python.

To build from source, use Rust 1.93 and a C compiler:

cargo install --git https://github.com/frgfm/lint-my-headers --locked

PyPI tooling requires Python 3.11+. Wheels ship native lmh and lint-my-headers executables; building a source distribution also requires Rust and a C compiler. See the installation guide for source checkout instructions and launcher details.

Quick start

Declare your project's actual owner and license in pyproject.toml, keep the matching LICENSE at the project root, and select the source folders that exist in your project:

[tool.lint-my-headers]
owner = "Example Organization"
starting-year = 2024
license = "Apache-2.0"
paths = ["src", "tests"]

Check existing headers:

lmh check

Findings tell you exactly where to look and whether a repair is available:

src/example.py:1:1: LMH004 copyright year ends at 2025; expected 2026 [fixable]

Refresh recognized stale years and review the result:

lmh fix
lmh check
git diff

A 2026 refresh produces a diff like this:

-# Copyright (C) 2024-2025, Example Organization.
+# Copyright (C) 2024-2026, Example Organization.

Only the end year changes. check never writes source files. Missing headers and other findings stay available for manual review. See the getting-started guide for a complete header example.

Benchmarks

Run bash scripts/benchmark.sh to generate CSVs, SVG/PNG charts and an HTML report with a workflow-overhead calculator. Add --compare /path/to/hawkeye for a locally measured comparison or --baseline /path/to/previous/lmh to show the improvement. See requirements and reproduction.

Configuration and safety

Keep the policy in the file your project already uses:

The CLI discovers the nearest policy by searching upward, with priority in that order; Cargo package metadata takes precedence over workspace metadata. Manifests without LMH settings are skipped. Invalid policies fail and configurations are never merged. --config selects an exact file; CLI options override file settings.

For multilingual projects, select the languages used by your codebase:

languages = ["python", "typescript", "rust"]

The default is Python. Configured paths are relative to the policy file; explicit CLI paths are relative to the invocation directory. Unsupported extensions are skipped. Exclude generated, dependency, and build folders with ignore-folders; LMH does not infer exclusions from .gitignore.

Repairs require one recognized stale year for the configured owner. Ambiguous layouts, wrong owners, future years, unsupported encodings, symlinks/reparse points, multiple hard links, and concurrently changed targets are refused. Ownership and licensing always come from your policy; LMH does not insert missing headers or establish legal, SPDX, or REUSE compliance.

See the configuration guide for all options, language aliases, supported extensions, notice formats, and byte-preservation rules.

Agents and JSON

Use the same CLI from scripts and coding agents:

lmh check --output-format json

JSON schema version 1 includes the checked count, completed changes, and diagnostics with path, line, column, code, message, and repair eligibility. Parsed JSON-mode commands write only JSON to stdout; malformed CLI syntax remains a stderr usage error.

An agent should read the declared policy, run check, repair only when source changes are authorized, then recheck and inspect the diff. A failed repair may follow earlier completed changes; review changed and the working tree before retrying.

Use the first-party agent skill and the diagnostics guide for the full contract. Retained agent evaluations are historical Python-era results, not measurements of the Rust CLI.

Integrations

pre-commit and prek

Use the published native wheel in an isolated Python 3.11+ hook environment. Select languages in your policy to enable multilingual checks:

repos:
  - repo: local
    hooks:
      - id: lmh
        name: Lint My Headers
        entry: lmh check
        language: python
        types: [file]
        additional_dependencies:
          - --only-binary=lint-my-headers
          - lint-my-headers==0.7.0

Alternatively, use the first-party source hook at the release tag:

repos:
  - repo: https://github.com/frgfm/lint-my-headers
    rev: v0.7.0
    hooks:
      - id: lmh

The source hook compiles Rust on first installation with the pinned toolchain. pre-commit's Rust installer does not pass --locked. Both hooks run read-only checks.

GitHub Action

Add the published release to your existing workflow:

steps:
  - uses: actions/checkout@v7
  - uses: frgfm/lint-my-headers@v0.7.0

The Action reads repository policy and uses uv to install the exact PyPI version with source builds disabled. Prefer immutable release SHAs; the v0.7.0 release notes provide its commit SHA. For an unreleased multilingual revision, pin its reviewed SHA and set version: source to build that Action checkout using Cargo.lock.

Inputs override policy. The issues and changed outputs are compact JSON path arrays; on exit 2, issues is empty and changed retains completed writes. An I/O error stops new repairs; already-running repairs finish before results are returned. See the integration guide and Action reference for all inputs, outputs, and installation behavior.

Annual copyright refresh

Create a review PR each January using the maintained workflow below.

[dependency-groups]
quality = ["lint-my-headers==0.7.0"]

headers-fix:
	uv run --locked --group quality lmh fix

name: update copyright years

on:
  schedule:
    - cron: "1 0 1 1 *"
      timezone: Europe/Paris

permissions:
  contents: read

concurrency:
  group: annual-copyright-years
  cancel-in-progress: false

jobs:
  update:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    env:
      TZ: Europe/Paris
      BASE_BRANCH: ${{ github.event.repository.default_branch }}
      UV_PROJECT_ENVIRONMENT: ${{ runner.temp }}/lmh-annual-env
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ github.event.repository.default_branch }}
          fetch-depth: 0
      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
        with:
          version: "0.12.5"
      - name: Create the annual pull request
        shell: bash
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail

          copyright_year="$(date +%Y)"
          branch_name="automation/update-copyright-years-$copyright_year"
          test "$branch_name" != "$BASE_BRANCH"

          pr_number="$(gh pr list --base "$BASE_BRANCH" --head "$branch_name" --state all --json number --jq '.[0].number // empty')"
          if test -n "$pr_number"; then
            echo "Annual pull request #$pr_number already exists."
            exit 0
          fi

          remote_sha="$(git ls-remote --heads origin "$branch_name" | cut -f1)"
          if test -z "$remote_sha"; then
            make headers-fix
            if git diff --quiet -- ':(glob)**/*.py'; then
              echo "Copyright years are already current."
              exit 0
            fi

            git switch -c "$branch_name"
            git config user.name "github-actions[bot]"
            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
            git add -u -- ':(glob)**/*.py'
            git commit -m "chore: update copyright years for $copyright_year"
            git push --set-upstream origin "$branch_name"
          fi

          gh pr create --base "$BASE_BRANCH" --head "$branch_name" \
            --title "chore: update copyright years for $copyright_year" \
            --body "Annual refresh of recognized Python copyright years using the declared header policy."

Contributing

Lint My Headers is open source under Apache-2.0. Contributions, bug reports, and feedback are welcome. See CONTRIBUTING.md for local development and checks, AGENTS.md for runtime contracts, and RELEASE_NOTES.md for release and migration notes.

Report a bug · Read the docs · View releases