Configuration Overview

Headroom uses three different sources of configuration, where the next one eventually overrides the previous one:

1. default configuration in embedded/default-config.yaml
2. custom configuration in .headroom.yaml
3. command line arguments

YAML Configuration

The YAML configuration file, located in .headroom.yaml, is the main and most capable configuration source for Headroom. Don't forget to check the default YAML configuration in embedded/default-config.yaml, both to know more about all possible configuration keys (it's well documented there), but also to know which value you need to override when in your custom .headroom.yaml.

Configuration Version

When Headroom is loading your .headroom.yaml file, it first checks whether your configuration is compatible with your version of Headroom. This is done by checking the version field. If you generated your configuration using Headroom's init or gen command, then this field was automatically set to correct value. You don't need to care about this field unless you upgrade your Headroom version, in case that this field will need to be updated, you'll be always informed by corresponding migration guide.

Top Level Overview

From top-level perspective, the YAML configuration has the following structure:

version: 1.2.3.4            ## Version of Headroom the configuration is compatible with
run-mode: ...               ## Default mode of the 'run' command
excluded-paths: []          ## Path(s) to exclude from 'source-paths'
exclude-ignored-paths: true ## Whether to exclude source paths ignored by GIT
source-paths: []            ## Path(s) to source code files to process headers in
template-paths: []          ## Path(s) to license header templates
variables: {}               ## Value(s) of variable(s) to replace in template(s)
license-headers: {}         ## License header detection & positioning
post-process: {}            ## Post-processing functions

Relation between Command-line Arguments and YAML Configuration

Not all configuration options can be set/overridden using the command line arguments, but below is the list of matching YAML options and command line options:

YAML option	Command Line Option
run-mode: add	-a, --add-headers
run-mode: drop	-d, --drop-headers
run-mode: replace	-r, --replace-headers
run-mode: check	-c, --check-headers
source-paths	-s, --source-path PATH
excluded-paths	-e, --excluded-path REGEX
exclude-ignored-paths	--exclude-ignored-paths
template-paths	-t, --template-path PATH
variables	-v, --variable "KEY=VALUE"

Where source-path, template-path and variable command line arguments can be used multiple times to set more values.

run-mode key

This configuration changes default behaviour of the run command. Possible values are add, drop, replace or check. For more details, see the Running Headroom chapter.

excluded-paths key

If you need to exclude selected paths from the list of paths defined in source-paths, you can use this option. The value of this configuration is list of regexes, so be aware of that when you exclude path with dot, as you need to escape it, like:

excluded-paths:
    - '\.stack-work'

exclude-ignored-paths key

If some paths within your source paths list are ignored by Git, you can either manually exclude them using the above key, but better way is to use this option. Using this configuration, Headroom will scan Git's ignore rules for current project and will automatically exclude appropriate source paths.

source-paths key

Defines list of paths to source code files to process. Note that given path, if directory, is recursively traversed for all types of source code files knowh to Headroom.

template-paths key

Defines list of template paths. Path can be either relative or absolute path of template stored on local file system, or URL pointing to template stored on Internet (note that only HTTP or HTTPS protocols are supported).

variables key

This is the main point where you define values for variables present in template files. Variables in Headroom can be split into two main categories:

• static variables - Variables that are defined by user and which values the same for all processed source code files (e.g. author variable that holds author's name).
• dynamic variables - Variables that are defined by Headroom and which values can vary file from file. Convention is that these variables are prefixed by underscore, so you can spot them easily. Below is the list of general dynamic variables, provided by Headroom:
  • _current_year - value of the current year (e.g. 2020) More dynamic variables might be exposed for individual processed files by the content-aware templates for selected types of source code files.

Also note that you can use reference other variables in variables, as long as you - don't call them recursively - don't define cyclic dependencies between them

Example of such nested reference is below:

variables:
    author: John Smith
    copyright: Copyright (c) {{ _current_year }} {{ author }}

license-headers key

This configuration allows to modify the behaviour how license headers are detected and/or rendered for each supported file type. As example, this is how default configuration for Haskell source code files looks like:

## Haskell configuration
haskell:
  file-extensions: ["hs"]
  margin-top-code: 0
  margin-top-file: 0
  margin-bottom-code: 0
  margin-bottom-file: 0
  put-after: []
  put-before: ["^module"]
  block-comment:
    starts-with: ^{-\|
    ends-with: (?<!#)-}$

If the default configuration for selected file type doesn't suit your needs, you can override following settings:

1. list of file extensions - if you need to match selected file type with different set of file extensions, override the file-extensions option.
2. margin around license header - if you want to add blank lines before and/or after generated license header, you can use one of the following options:
   • margin-top-code - defines margin (in no. of empty lines) between generated header and code above it, but only IF header is NOT the first thing in file.
   • margin-top-file - defines margin (in no. of empty lines) between generated header the very top of the file, but only IF header IS the first thing in file.
   • margin-bottom-code - defines margin (in no. of empty lines) between generated header and code below it, but only IF header is NOT the last thing in file.
   • margin-bottom-file - defines margin (in no. of empty lines) between generated header the very end of the file, but only IF header IS the last thing in file.
3. put header before/after pattern - you can define before and/or after which pattern Headroom will put the license header (such as before the line starting with module in Haskell code).
4. syntax of header comment - license header can be represented by either single block comment (such as {- -} in Haskell) or bunch of single line comments (such as // in C/C++ or -- in Haskell). Block comment can be defined by using the use the block-comment option with starts-with and ends-with sub-options, line comment by line-comment option with prefixed-by sub-option. Note that all these options expects valid regular expressions.

post-process key

This is the configuration for post-processing functions. See more details in Post-processing functions chapter.

Supported License Types

Headroom provides built-it license templates for major OSS licenses. Whenever you need to specify the license type in .headroom.yaml or command line arguments, use one of the values below:

License	Name in configuration
Apache 2.0	apache2
BSD 3-Clause	bsd3
GPLv2	gpl2
GPLv3	gpl3
MIT	mit
MPL2	mpl2

If you miss support for license type you use, feel free to open new issue.

Supported File Types

Headroom can manage license headers only for supported types of source code files. Whenever you need to specify the license type in .headroom.yaml or command line arguments, use one of the values below:

Language	Name in configuration	Default extensions
C	c	.c
C++	cpp	.cpp
CSS	css	.css
Go	go	.go
Haskell	haskell	.hs
HTML	html	.html, .htm
Java	java	.java
JavaScript	js	.js
PureScript	purescript	.purs
Rust	rust	.rs
Scala	scala	.scala
Shell	shell	.sh

If you miss support for file type you use, feel free to open new issue.