headerkit

headerkit keeps license and copyright headers correct across polyglot repositories. It adds missing headers, repairs outdated copyright years from git history, detects files that declare the wrong license, and fails CI when a header drifts. It understands 43 languages, including shebangs, encoding lines, XML prologs, PHP open tags, doctypes, Go build tags and Python docstrings, and it never touches generated, vendored or binary files.

Features

• Language registry (43) with line, block, HTML and OCaml comment styles and per-language rules for what must stay above the header (see docs/languages.md).
• Templates: SPDX short form or standard short notices (MIT, BSD-2/3-Clause, ISC, Apache-2.0, GPL-3.0-or-later, MPL-2.0), custom templates with {year}, {years}, {owner}, {project}, {license}, and per-path overrides by glob.
• Year logic: first-last commit year per file from one git log pass (rename-aware), or fixed years. Existing owner lines are preserved; multiple holders are supported.
• check: missing, outdated-year, wrong-license, malformed and missing-owner findings with fix hints; text, JSON, SARIF 2.1.0 and GitHub annotation output; CI-friendly exit codes.
• fix: in-place insert/update, idempotent, preserves line endings and BOM. Wrong licenses are only rewritten with --relicense.
• report: license inventory by SPDX id, files lacking an SPDX tag, conflicting licenses.
• strip: remove headers.
• Skips generated files (Code generated ... DO NOT EDIT), vendored directories, binaries, empty files and anything git ignores. Checking 4000 files takes about a fifth of a second.

Install

uv venv .venv && uv pip install -p .venv/bin/python -e '.[dev]'
source .venv/bin/activate    # or call .venv/bin/headerkit directly

Requires Python 3.12+ and git (for year logic). The only dependency is click.

Quickstart

./examples/make_sample_repo.sh /tmp/sample   # a polyglot repo with planted problems and dated history
cd /tmp/sample
headerkit check          # exit 1, lists every problem
headerkit fix            # repair everything that is safe to repair
headerkit check          # exit 1: only src/Main.java (wrong license) remains; see `fix --relicense` below

In your own repository run headerkit init --license MIT --owner "Your Name", edit headerkit.toml, then headerkit check.

Usage

Global options (before the command): -C/--root DIR (project root, default .) and -c/--config FILE. Every command except init accepts optional PATHS to restrict the scan to files or directories. The output below was captured on the sample repo built by examples/make_sample_repo.sh.

check

$ headerkit check
Makefile:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
Tool.cs:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
config/pom.xml:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
public/index.php:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
scripts/build.rb:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
scripts/deploy.sh:2: malformed: license notice detected as MIT but there is no SPDX-License-Identifier line
    hint: run `headerkit fix` to rewrite the header in SPDX form
scripts/deploy.sh:5: outdated-year: copyright has 2020, git history says 2023
    hint: run `headerkit fix` to update the years
sql/schema.sql:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
src/Main.java:1: wrong-license: header declares GPL-3.0-or-later, expected MIT
    hint: run `headerkit fix --relicense` if the file really is relicensed, or add a [[override]] for its path
src/app.py:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
src/db.go:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
src/lib.rs:1: malformed: header has no SPDX tag or recognised license notice
    hint: run `headerkit fix` to add `MIT`
src/server.js:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
src/shared.py:1: missing-owner: no copyright line for Acme Robotics Ltd
    hint: run `headerkit fix` to add it
src/util.py:1: outdated-year: copyright has 2019, git history says 2019-2024
    hint: run `headerkit fix` to update the years
web/index.html:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
web/style.css:1: missing: no license header
    hint: run `headerkit fix` to add a MIT header
18 files checked, 16 with issues (17 problems)

Formats: --format text|json|github|sarif. GitHub annotations look like:

::error file=Makefile,line=1,title=headerkit HK001::no license header. run `headerkit fix` to add a MIT header
::error file=Tool.cs,line=1,title=headerkit HK001::no license header. run `headerkit fix` to add a MIT header
::error file=config/pom.xml,line=1,title=headerkit HK001::no license header. run `headerkit fix` to add a MIT header

Exit codes: 0 clean, 1 problems found, 2 usage or configuration error.

fix

$ headerkit fix
fixed Makefile (missing)
fixed Tool.cs (missing)
fixed config/pom.xml (missing)
fixed public/index.php (missing)
fixed scripts/build.rb (missing)
fixed scripts/deploy.sh (malformed, outdated-year)
fixed sql/schema.sql (missing)
skipped src/Main.java: header declares GPL-3.0-or-later, expected MIT (use --relicense or an [[override]])
fixed src/app.py (missing)
fixed src/db.go (missing)
fixed src/lib.rs (malformed)
fixed src/server.js (missing)
fixed src/shared.py (missing-owner)
fixed src/util.py (outdated-year)
fixed web/index.html (missing)
fixed web/style.css (missing)
15 files changed, 1 skipped

src/Main.java declares GPL-3.0-or-later in an MIT project, so it is reported and left alone. After reviewing it, --relicense replaces it:

$ headerkit fix --relicense
fixed src/Main.java (wrong-license)
1 files changed, 0 skipped

Changes are minimal. A stale year is edited in place, and a free-form permission notice is replaced by the SPDX form:

diff --git a/scripts/deploy.sh b/scripts/deploy.sh
--- a/scripts/deploy.sh
+++ b/scripts/deploy.sh
@@ -1,8 +1,6 @@
 #!/bin/sh
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software, to deal in the Software without restriction.
-#
-# Copyright 2020 Acme Robotics Ltd
+# Copyright 2020-2023 Acme Robotics Ltd
+# SPDX-License-Identifier: MIT

 set -eu
 echo "deploying"
diff --git a/src/util.py b/src/util.py
--- a/src/util.py
+++ b/src/util.py
@@ -1,4 +1,4 @@
-# Copyright (c) 2019 Acme Robotics Ltd
+# Copyright (c) 2019-2024 Acme Robotics Ltd
 # SPDX-License-Identifier: MIT

 def greet(name: str) -> str:

--dry-run lists what would change without writing. Afterwards:

$ headerkit check
src/Main.java:1: wrong-license: header declares GPL-3.0-or-later, expected MIT
    hint: run `headerkit fix --relicense` if the file really is relicensed, or add a [[override]] for its path
18 files checked, 1 with issues (1 problems)

report

$ headerkit report
Scanned 18 files (skipped: excluded 2, generated 1, unsupported 1)

Licenses by SPDX identifier
  MIT                                   3
  GPL-3.0-or-later                      1
  Apache-2.0 (notice, no SPDX tag)      1
  MIT (notice, no SPDX tag)             1
  (copyright only, no license text)     1
  (no header)                          11

Languages
  python 3, makefile 1, csharp 1, xml 1, c 1, php 1, ruby 1, shell 1, sql 1, java 1, go 1, typescript 1, rust 1, javascript 1, html 1, css 1

Files lacking an SPDX tag (14)
  Makefile
  Tool.cs
  config/pom.xml
  legacy/old.c
  public/index.php
  scripts/build.rb
  scripts/deploy.sh
  sql/schema.sql
  src/app.py
  src/db.go
  src/lib.rs
  src/server.js
  web/index.html
  web/style.css

Conflicts (1)
  copyleft license GPL-3.0-or-later inside a project licensed MIT

report --format json gives the same data as JSON. --fail-on-conflict exits 1 if conflicts exist (copyleft inside a permissive project, GPL-2.0-only mixed with Apache-2.0 or GPL-3.0).

strip

headerkit strip [--dry-run] [PATHS] removes detected license headers and the blank line that followed them.

Configuration

[headerkit]
license = "MIT"
style = "spdx"                 # or "notice"
owner = ["Acme Robotics Ltd"]  # one or several holders
project = "Acme Toolkit"
year_mode = "git"              # or "fixed" with year = "2020-2024"
exclude = ["docs/**"]

[[override]]
glob = "legacy/**"
license = "Apache-2.0"
style = "notice"

All keys, glob rules, templates and output formats are described in docs/configuration.md.

Architecture

Algorithms and worked examples: docs/design.md.

Tests

.venv/bin/pytest -q

132 tests: golden insertion files per language and licence style (tests/golden/), git-history year ranges against temporary repositories (renames, subdirectory roots), idempotency, license detection, config validation and CLI behaviour end to end.

Limitations

• Only the first comment of a file is treated as the header.
• Rebuilding a malformed header keeps copyright lines but drops other lines inside the old header.
• Years reflect committed history; uncommitted edits are ignored on purpose so that fix stays idempotent. In CI use a full clone (fetch-depth: 0).
• Notices are short standard boilerplate and pointers to the LICENSE file, not full license texts.
• Non-UTF-8 files are skipped. JSON, Markdown and other comment-less formats are not handled.
• Conflict detection is a small heuristic table, not legal advice.

License

MIT, see LICENSE.