headroom: License Header Manager

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
  • 3.1. From Source Code
    • 3.1.1. Using Cabal
    • 3.1.2. Using Stack
• 4. Basic Overview
  • 4.1. Main Concepts
  • 4.2. License Header Detection
• 5. Quick Start Guide
  • 5.1. Initializing Headroom
    • 5.1.1. Automatic Initialization
    • 5.1.2. Manual Initialization
  • 5.2. YAML Configuration File
  • 5.3. Running Headroom
• 6. Command Line Interface Overview
  • 6.1. Init Command
  • 6.2. Run Command
  • 6.3. Generator Command
    • 6.3.1. Supported License Types
    • 6.3.2. Supported File Types

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

3. Installation

Binary distribution will be available soon, there are also plans to add Headroom to popular package managers.

3.1. From Source Code

Headroom is written in Haskell, so you can install it from source code either using Cabal or Stack.

3.1.1. Using Cabal

1. install Cabal for your platform
2. run cabal install headroom
3. add $HOME/.cabal/bin to your $PATH

3.1.2. Using Stack

1. install Stack for your platform
2. run stack install headroom
3. add $HOME/.local/bin to your $PATH

4. Basic Overview

4.1. Main Concepts

1. 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.).
2. 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.
3. 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:

1. .headroom.yaml configuration file with correctly set path to template files, source codes and will contain dummy values for variables.
2. 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: john.smith@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:

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.