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. Case Example
  • 4.1. Adding License Header Templates
  • 4.2. Adding Headroom Configuration
  • 4.3. Running Headroom
• 5. Command Line Interface Overview
  • 5.1. Run Command
  • 5.2. Generator Command
    • 5.2.1. Supported License Types
    • 5.2.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.

2. Planned Features

• [#24] Init Command - automates initial Headroom setup for your project (generates config files, detects source code file types and generates license template stubs for them)
• Binary Distribution - pre-built binaries will be generated for each release for major OS platforms

3. Installation

Binary distribution, pre-built packages and installation from Stackage will be available soon.

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. clone this repository
3. run stack install inside the headroom/ directory
4. add $HOME/.local/bin to your $PATH

4. Case Example

Let's demonstrate how to use Headroom in real world example: imagine 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

4.1. Adding License Header Templates

Let's say our project is licensed under the 3-Clause BSD License license, so we want to use appropriate license headers. Headroom already provides templates for this license which you can use without modifications, or as starting point for your customization. Now we need to generate template file for each source code file type we have. The template must be always named as <FILE_TYPE>.mustache, for reference see list of supported file types and supported license types.

cd project/
mkdir templates/
cd templates/

headroom gen -l bsd3:css >./css.mustache
headroom gen -l bsd3:html >./html.mustache
headroom gen -l bsd3:scala >./scala.mustache

Now the project structure should be following:

project/
  ├── src/
  │   ├── scala/
  │   │   ├── Foo.scala
  │   │   └── Bar.scala
  │   └── html/
  │       └── template1.html
  └── templates/
      ├── css.mustache
      ├── html.mustache
      └── scala.mustache

4.2. Adding Headroom Configuration

Now we need to add configuration file where we specify path to source code files, template files and define values for variables in templates. The configuration file should be placed in project root directory and should be named .headroom.yaml, so Headroom can locate it:

cd project/
headroom gen -c >./.headroom.yaml

The project structure should now be following:

project/
  ├── src/
  │   ├── scala/
  │   │   ├── Foo.scala
  │   │   └── Bar.scala
  │   └── html/
  │       └── template1.html
  ├── templates/
  │   ├── css.mustache
  │   ├── html.mustache
  │   └── scala.mustache
  └── .headroom.yaml

Let's now edit configuration file to match our project:

## This is the configuration file for Headroom.
## See https://github.com/vaclavsvejcar/headroom for more details.

## Defines the behaviour how to handle license headers, possible options are:
##   - add     = (default) adds license header to files with no existing header
##   - drop    = drops existing license header from without replacement
##   - replace = adds or replaces existing license header
run-mode: add

## Paths to source code files (either files or directories).
source-paths:
    - src

## Paths to template files (either files or directories).
template-paths:
    - templates

## Variables (key-value) to replace in templates.
variables:
    author: John Smith
    year: "2019"

4.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

5. 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.0.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

5.1. 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:

5.2. 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.

5.2.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.

5.2.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.