Running Headroom

After you set up Headroom for your project, you should be ready to run it. Below is the overview of the command line interface that Headroom provides.

Commands

Headroom provides three different commands, you might already familiar with the gen or init command from the Project Setup Guide chapter:

1. run - this is the main command and the one you'll use the most. It allows you to add, replace, drop or check license headers in source code files.
2. gen - this command allows to generate files stub required by Headroom, such as YAML configuration file or license templates for selected OOS license.
3. init - this command simplifies Headroom setup by automatically scanning your project and generating proper .headroom.yaml and template files.

Run Command

Let's start with the most useful one. This command allows you to manipulate license headers in source code files, and provides four different modes to do so:

1. add mode (default one) - will only add missing license headers, but won't touch existing ones.
2. replace mode - will add missing license headers, but also replace any already existing ones (if differs).
3. check mode - checks that all your source code files have up-to-date license headers, without actually touching any files. When any file with outdated license header is detected, Headroom execution will result in return code 1, so you can easily use this mode in your CI pipelines, etc.
4. drop mode - will drop any existing license headers, without replacement.

Command Line Interface

Below is the overview of command line interface of run command:

$ headroom run --help
Usage: headroom run [-s|--source-path PATH] [-e|--excluded-path REGEX] 
                    [--builtin-templates licenseType] [-t|--template-path PATH] 
                    [-v|--variable KEY=VALUE] 
                    [(-a|--add-headers) | (-c|--check-headers) | 
                      (-r|--replace-headers) | (-d|--drop-headers)] [--debug] 
                    [--dry-run]
  add, replace, drop or check source code headers

Available options:
  -s,--source-path PATH    path to source code file/directory
  -e,--excluded-path REGEX path to exclude from source code file paths
  --builtin-templates licenseType
                           use built-in templates of selected license type
  -t,--template-path PATH  path to template, can be either local file or
                           directory or URL
  -v,--variable KEY=VALUE  value for template variable
  -a,--add-headers         only adds missing license headers
  -c,--check-headers       check whether existing headers are up-to-date
  -r,--replace-headers     force replace existing license headers
  -d,--drop-headers        drop existing license headers only
  --debug                  produce more verbose output
  --dry-run                execute dry run (no changes to files)
  -h,--help                Show this help text

This command requires you to specify three key parameters, either using command line option, or in .headroom.yaml file:

1. paths to source code files - this needs to be specified either by using the -s|--source-path PATH option (can be repeated) or using the source-paths option in .headroom.yaml.
2. paths to templates - you can freely combine all three supported sources of templates: First are built-in templates for one of supported OSS licenses, which can be enabled by --builtin-templates TYPE. Second option is to use either templates stored on local file system or URI-based template. For local stored template, if path to directory is provided, Headroom will recursively search for all suitable templates in all subdirectories.
3. paths to template files - you have two options here. Either specify path(s) to template files using -t|--template-path PATH (can be repeated) or template-paths option in .headroom.yaml, or use the built-in templates using the --builtin-templates TYPE, where TYPE is one of the supported OSS license types.
4. variables - if your templates use any variables, you need to specify their values using the -v|--variable "KEY=VALUE" option (can be repeated) or using the variable option in .headroom.yaml.
5. run mode (optional) - if you don't specify this, the add mode will be used as default, but you can set the run mode using one of the -a,--add-headers, -c,--check-headers, -r,--replace-headers or -d,--drop-headers options, or using the run-mode option in .headroom.yaml.

For regular work, it's more comfortable to define as much options in .headroom.yaml and then you can just run Headroom like headroom run or just override the run mode like headroom run -r, but it's also completely fine to run Headroom without the need to prepare any files (templates, .headroom.yaml) and define all the required stuff using command line options, as shown below:

Gen Command

This command allows to generate stubs for files required by Headroom, such as .headroom.yaml and template files. You'll likely need this command only once for manual initialization of Headroom for your project. For more info how to use it, see the Project Setup Guide chapter.

Command Line Interface

Below is the overview of command line interface of gen command:

$ headroom gen --help
Usage: headroom gen [-c|--config-file] [-l|--license licenseType:fileType]
  generate stub configuration and template files

Available options:
  -c,--config-file         generate stub YAML config file to stdout
  -l,--license licenseType:fileType
                           generate template for license and file type
  -h,--help                Show this help text

Main things you can do with this command is to generate:

1. configuration file - using the headroom gen -c >.headroom.yaml, you'll generate stub for the main configuration file
2. template files - using the headroom gen -l haskell:bsd3 >templates/haskell.mustache, you'll generate stub license template file for Haskell file type and BSD-3-Clause license. See all supported file types and license types in Configuration chapter.

Init Command

This command is used to initialize Headroom for your project by generating the .headroom.yaml configuration file and template files for selected OSS license.

Command Line Interface

Below is the overview of command line interface of init command:

$ headroom init --help
Usage: headroom init (-l|--license-type TYPE) (-s|--source-path PATH)
  initialize current project for Headroom

Available options:
  -l,--license-type TYPE   type of open source license, available options:
                           apache2, bsd3, gpl2, gpl3, mit, mpl2
  -s,--source-path PATH    path to source code file/directory
  -h,--help                Show this help text

With this command, you need to define two required options:

1. license type - type of the OSS license your project uses. See Configuration chapter for list of all supported licenses.
2. path to source code files - using the -s|--source-path PATH (can be repeated), you need to define path(s) to source code files which license headers will be managed by Headroom.