Configuration

headerkit reads headerkit.toml (or .headerkit.toml) from the project root, or the file given with --config. headerkit init writes a starter file. The config file itself is never scanned.

`[headerkit]`

Key	Default	Meaning
`license`	required	SPDX identifier (or expression) every file should carry, e.g. `MIT`, `Apache-2.0`, `MIT OR Apache-2.0`.
`owner`	required	Copyright holder, or a list of holders. Every holder gets a copyright line.
`project`	root directory name	Substituted for `{project}` in notices.
`style`	`spdx`	`spdx` writes `Copyright` + `SPDX-License-Identifier`. `notice` writes the standard boilerplate for `license`. Notice templates exist for `MIT`, `BSD-2-Clause`, `BSD-3-Clause`, `ISC`, `Apache-2.0`, `GPL-3.0-or-later`, `MPL-2.0`.
`template`	none	Custom multi-line template (implies `style = "custom"`). Variables: `{year}` (last year), `{years}` (`2019-2026` or `2024`), `{owner}`, `{project}`, `{license}`. Any line containing `{owner}` is repeated per owner.
`year_mode`	`git`	`git`: years from commit history. `fixed`: use `year`.
`year`	none	With `year_mode = "fixed"`: `"2024"` or `"2020-2024"`.
`exclude`	`[]`	Glob patterns of files to ignore.
`default_excludes`	`true`	Also ignore `.git node_modules vendor third_party __pycache__ .venv venv .tox .mypy_cache dist build target` directories at any depth.
`skip_generated`	`true`	Skip files whose first 30 lines mark them as generated (`Code generated ... DO NOT EDIT`, `@generated`, `auto-generated`, `generated by`).

`[[override]]`

Per-path rule changes. Each block needs glob and may set license, style, owner, project, template or skip = true. Overrides are applied in file order, so later blocks win.

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

[[override]]
glob = "generated_clients/**"
skip = true

`[extensions]`

Map extra extensions to a built-in language name (see languages.md):

[extensions]
tpl = "html"

Globs

* matches within a path segment, ** across segments, ? one character. A pattern without / matches a file name at any depth (*.min.js). A trailing / means "everything under this directory". Paths are relative to the root with / separators.

Exit codes

Code	Meaning
0	`check`: every header is fine. `fix`/`strip`/`report`: success.
1	`check`: problems found. `report --fail-on-conflict`: conflicts found.
2	Usage or configuration error (no config, bad TOML, unknown key, path outside the root).

Output formats (`check --format`)

text (default): path:line: kind: message plus a hint: line.
json: {checked, files_with_issues, issues: [{path, line, kind, rule, message, hint}]}.
github: ::error file=...,line=...,title=headerkit HK001::... workflow commands.
sarif: SARIF 2.1.0 for code scanning upload.

Kind	Rule	Level
`missing`	HK001	error
`outdated-year`	HK002	warning
`wrong-license`	HK003	error
`malformed`	HK004	error
`missing-owner`	HK005	warning

CI example

- run: pip install headerkit
- run: headerkit check --format github

For code scanning: headerkit check --format sarif > headerkit.sarif || true then upload the file. Remember that years come from git history, so check out with fetch-depth: 0.

Configuration

[headerkit]

[[override]]

[extensions]