Keep license and copyright headers consistent across your source code.
Headroom adds, updates, checks, and removes license headers in source code files. Define a header once as a Mustache template, keep its variables in a YAML configuration file, and apply it consistently across your project.
Headroom includes templates for popular open source licenses, understands the structure of selected source file types, and conservatively recognizes legacy headers from their license content.
Install Headroom with Homebrew, then initialize it in your project:
brew install norcane/tools/headroom
headroom init --license-type mit --source-path srcReview the variables generated in .headroom.yaml, preview the changes, and apply them:
headroom run --dry-run
headroom runYou can also verify that all headers are up to date without modifying any files, which is useful in CI:
headroom run --check-headersSee the Project Setup Guide for custom templates, multiple source directories, and other setup options.
Given a template such as headroom-templates/python.mustache:
# Copyright (c) {{ year }} {{ author }}
# SPDX-License-Identifier: MITAnd variables in .headroom.yaml:
variables:
author: "Jane Doe"
year: "2026"Headroom renders the header in each matching source file:
# Copyright (c) 2026 Jane Doe
# SPDX-License-Identifier: MIT
- Safe header management — Add, replace, check, or remove owned headers while preserving unrelated source documentation and comments.
- Built-in OSS licenses — Generate ready-to-use templates for popular open source licenses.
- Flexible configuration — Control source paths, exclusions, margins, comment styles, and header placement through YAML.
- Content-aware templates — Use information extracted from the processed file, such as a Java package name or Haskell module metadata.
- Copyright year updates — Keep years and year ranges in copyright notices current.
- Safe workflows — Preview changes with
--dry-run, validate them in CI, and initialize projects without overwriting existing files.
Headroom includes templates for these licenses:
| License | Configuration value |
|---|---|
| Apache License 2.0 | apache2 |
| BSD 3-Clause | bsd3 |
| GNU GPL v2 | gpl2 |
| GNU GPL v3 | gpl3 |
| MIT | mit |
| Mozilla Public License 2.0 | mpl2 |
Supported file types include C, C++, CSS, Dart, Go, Haskell, HTML, Java, JavaScript, Kotlin, Nix, PHP, PureScript, Python, Rust, Scala, Shell, and XML. See the configuration reference for extensions and file-type-specific options.
brew install norcane/tools/headroomcabal install headroomPre-built x64 binaries for GNU/Linux and macOS are available on the releases page.
Headroom can be built with Cabal or Stack. See the installation guide for requirements and detailed instructions.
The master branch may contain changes that have not yet been published to Hackage. See the changelog for version details.
- Project Setup Guide
- Command-line reference
- Configuration reference
- Template documentation
- Post-processing functions
- Haskell API on Hackage
Bug reports and pull requests are welcome. You can open an issue or submit a pull request on GitHub.
To preview the documentation locally, run:
cd doc/microsite/
mkdocs serveThe microsite will be available at http://127.0.0.1:8000.
- kowainik/hit-on — Kowainik Git Workflow Helper Tool
- kowainik/summoner — Tool for scaffolding batteries-included production-level Haskell projects
- wireapp/wire-server — Wire back-end services (https://wire.com)
Using Headroom in your project? Feel free to open an issue or submit a pull request to add it to this list.
- Issue #2 of Bind the Gap magazine includes a chapter dedicated to Headroom (pages 17–18).
Headroom is distributed under the BSD 3-Clause License.