Configuration Overview

Headroom uses two main sources of configuration, global configuration, shared between all Headroom instances, and application configuration, that is specific for project in which Headroom is executed.

Global Configuration¶

This configuration is used to configure some global rules that are applied for all instances of Headroom, for example whether Headroom should automatically check for updates, etc. It's located in directory in user's home directory (~/.headroom) and has following structure:

~/.headroom
├── cache.sqlite
└── global-config.yaml

Where:

cache.sqlite is key-value cache (SQLite database) used by Headroom to store some values, such as when was the last attemt to check updates done
global-config.yaml is the global configuration YAML file

YAML File Structure¶

Below is the structure of global-config.yaml configuration file:

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

## Configuration for Headroom Updater.
updates:

  ## Whether Headroom should automatically check for available updates. 
  check-for-updates: true

  ## How often (in days) should Headroom check for updates.
  update-interval-days: 1

At this moment, only configuration of automatic updates is present.

Application Configuration¶

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

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

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:

list of file extensions - if you need to match selected file type with different set of file extensions, override the file-extensions option.
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.
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).
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`
Dart	`dart`	`.dart`
Go	`go`	`.go`
Haskell	`haskell`	`.hs`
HTML	`html`	`.html`, `.htm`
Java	`java`	`.java`
JavaScript	`js`	`.js`
PHP	`php`	`.php`
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.

Configuration Overview

Global Configuration¶

YAML File Structure¶

Application Configuration¶

Configuration Version¶

Top Level Overview¶

Relation between Command-line Arguments and YAML Configuration¶

run-mode key¶

excluded-paths key¶

exclude-ignored-paths key¶

source-paths key¶

template-paths key¶

variables key¶

license-headers key¶

post-process key¶