So you are tired of managing license headers in your codebase by hand? Then Headroom is the right tool for you! Now you can define your license header as Mustache template, put all the variables (such as author's name, year, etc.) into the YAML config file and Headroom will take care to add such license headers to all your source code files.
Table of Contents
- 1. Main Features
- 2. Planned Features
- 3. Installation
- 4. Basic Overview
- 5. Quick Start Guide
- 6. Command Line Interface Overview
1. Main Features
- License Header Management - allows to add, replace or drop license headers in source code files.
- License Header Autodetection - you can even replace or drop license headers that weren't generated by Headroom, as they are automatically detected from source code files, not from template files.
- Template Generator - generates license header templates for most popular open source licenses. You can use these as-is, customize them or ignore them and use your custom templates.
- Automatic Initialization - using the Init command, Headroom can detect what source code files you have in your project and generate initial configuration file and appropriate template skeletons.
2. Planned Features
- [#25] Content-aware Templates - license header templates will be able to extract some template variables from source code file for which the template is rendered
- Binary Distribution - pre-built binaries will be generated for each release for major OS platforms
Binary distribution will be available soon, there are also plans to add Headroom to popular package managers.
3.1. From Source Code
3.1.1. Using Cabal
- install Cabal for your platform
cabal install headroom
3.1.2. Using Stack
- install Stack for your platform
stack install headroom
4. Basic Overview
4.1. Main Concepts
- Template files - Template files contains templates in Mustache format, used for rendering license headers. During rendering phase, all variables are replaced by values loaded from YAML configuration file. Each supported source code file has unique template, because license headers may differ for individual programming languages (i.e. different syntax for comments, etc.).
- Source Code Files - Headroom automatically discovers individual source code files in configured location and can manage (add/remove/drop) license headers in supported types of source code files.
- Variables - are defined in YAML configuration file and these values are used to replace variables present in the template files.
4.2. License Header Detection
Unlike many other tools, Headroom can not only add, but also replace or drop existing license headers in source code files, even if there is already some header not generated by Headroom. This is done by implementing unique detection logic for each individual supported file type, but usually it's expected that the very first block comment is the license header. If you miss support for your favorite file type, please open new issue.
5. Quick Start Guide
Let's demonstrate how to use Headroom in real world example: assume you have small source code repository with following structure and you'd like to setup Headroom for it:
project/ └── src/ ├── scala/ │ ├── Foo.scala │ └── Bar.scala └── html/ └── template1.html
5.1. Initializing Headroom
5.1.1. Automatic Initialization
Easiest and fastest way how to initialize Headroom for your project is to use the Init command, which generates all the boilerplate for you. The only drawback is that you can use it only in case that you use any supported open source license for which Headroom contains license header templates:
cd project/ headroom init -l bsd3 -s src/
This command will automatically scan source code directories for supported file types and will generate:
.headroom.yamlconfiguration file with correctly set path to template files, source codes and will contain dummy values for variables.
headroom-templates/directory which contains template files for all known file types you use in your project and for open source license you choose.
Now the project structure will be following:
project/ ├── src/ │ ├── scala/ │ │ ├── Foo.scala │ │ └── Bar.scala │ └── html/ │ └── template1.html ├── headroom-templates/ │ ├── html.mustache │ └── scala.mustache └── .headroom.yaml
5.1.2. Manual Initialization
If you for some reason don't want to use the automatic initialization using the steps above, you can either create all the required files (YAML configuration and template files) by hand, or you can use the Generator command to do that in semi-automatic way:
cd project/ headroom gen -c >./.headroom.yaml mkdir headroom-templates/ cd headroom-templates/ headroom gen -l bsd3:css >./css.mustache headroom gen -l bsd3:html >./html.mustache headroom gen -l bsd3:scala >./scala.mustache
After these steps, make sure you set correctly the paths to template files and source code files in the YAML configuration file.
5.2. YAML Configuration File
Headroom's YAML configuration file must be placed in root of your project and called
.headroom.yaml. The configuration itself is pretty simple and consists of following keys:
run-mode: add source-paths: - . template-paths: - headroom-templates variables: author: John Smith email: email@example.com project: My project year: '2020'
run-mode- sets the default behaviour of Run command (
headroom run). Possible options are:
add- Headroom will only add license headers to source code where these are missing, but won't touch files with existing headers
drop- Headroom will drop existing license headers without any replacement
replace- Headroom will add missing or replace existing license headers
source-paths- paths to source code files (either files or directories)
template-paths- paths to template files (either files or directories)
variables- variables (key-value) to replace in templates
These settings can be then overriden by corresponding command line optionss. See more details about these settings in command line interface overview section below.
5.3. Running Headroom
Now we're ready to run Headroom:
cd project/ headroom run # adds license headers to source code files headroom run -r # adds or replaces existing license headers headroom run -d # drops existing license headers from files
6. Command Line Interface Overview
Headroom provides various commands for different use cases. You can check commands overview by performing following command:
$ headroom --help headroom v0.1.3.0 :: https://github.com/vaclavsvejcar/headroom Usage: headroom COMMAND manage your source code license headers Available options: -h,--help Show this help text Available commands: run add or replace source code headers gen generate stub configuration and template files init initialize current project for Headroom
6.1. Init Command
Init command is used to initialize Headroom for project by generating all the required files (YAML config file and template files). You can display available options by running following command:
$ headroom init --help Usage: headroom init (-l|--license-type LICENSE_TYPE) (-s|--source-path PATH) initialize current project for Headroom Available options: -l,--license-type LICENSE_TYPE type of open source license -s,--source-path PATH path to source code file/directory -h,--help Show this help text
6.2. Run Command
Run command is used to manipulate (add, replace or drop) license headers in source code files. You can display available options by running following command:
$ headroom run --help Usage: headroom run [-s|--source-path PATH] [-t|--template-path PATH] [-v|--variable KEY=VALUE] ([-r|--replace-headers] | [-d|--drop-headers]) [--debug] add or replace source code headers Available options: -s,--source-path PATH path to source code file/directory -t,--template-path PATH path to header template file/directory -v,--variable KEY=VALUE values for template variables -r,--replace-headers force replace existing license headers -d,--drop-headers drop existing license headers only --debug produce more verbose output -h,--help Show this help text
Note that command line options override options set in the configuration YAML file. Relation between command line options and YAML configuration options is below:
|YAML option||Command Line Option|
6.3. Generator Command
Generator command is used to generate stubs for license header template and YAML configuration file. You can display available options by running following command:
$ headroom gen --help Usage: headroom gen [-c|--config-file] [-l|--license name:type] generate stub configuration and template files Available options: -c,--config-file generate stub YAML config file to stdout -l,--license name:type generate template for license and file type -h,--help Show this help text
When using the
-l,--license option, you need to select the license type and file type from the list of supported ones listed bellow. For example to generate template for Apache 2.0 license and Haskell file type, you need to use the
headroom gen -l apache2:haskell.
6.3.1. Supported License Types
Below is the list of supported open source license types. If you miss support for license you use, feel free to open new issue.
6.3.2. Supported File Types
Below is the list of supported source code file types. If you miss support for programming language you use, feel free to open new issue.
|Language||Used Name||Supported Extensions|