Skip to content

Basic Concepts

Before we'll dive deeper into describing features and configuration options, let's introduce some top level overview of how Headroom works and what it does.

Why Headroom?

It's good to have copyright/license headers at the very top of each source code file, but it's not only cumbersome but also prone to errors to manage them by hand. You add some new source files in rush and forgot to copy the license header into them. Or you just need to update some info in them and hope that find&replace will do the job, and so on. Why to do this by hand, when some software could do that for you? This is why was Headroom created. The only thing you need to do is to set up Headroom for your project and then it will do all the dirty job for you.

How it works?

Simply said, Headroom takes Mustache templates of license headers, fills any variables by values taken from .headroom.yaml configuration file, renders them and puts them onto specified position in your source code files. And that's pretty much all. It has some advanced configuration options and another fancy features, but we'll get back to them in later chapters.

Before continuing to next chapters, here's the overview of key parts of Headroom. They will be described in more depth in Configuration chapter.

  • Configuration - Main source of configuration is the .headroom.yaml file that you put into your project directory. This is the place where Headroom looks for things such as where are source code files stored, where are license template files and what variables should be replaced in templates. It also offers some more advanced options such as to specify before/after which pattern to put the license headers, define blank lines as margin around the license header, etc.

  • Source Code Files - Those are the files in which the license headers should be managed by Headroom. You can specify multiple different locations and also paths that should be excluded.

  • Header Templates - Headroom uses Mustache templates to define the license headers. These templates are then compiled, variables are filled with actual and such rendered license headers are put into source code files. At this moment Headroom allows to define 3 different template sources: built-in templates (for popular OSS licenses), templates stored on local file system and URL-based templates.

  • Variables - Changing parts of license headers (such as year, author, e-mail, etc.) can be represented by variables and the actual values are then loaded from either .headroom.yaml or command line arguments and filled in during template rendering.

  • Post-processing Functions - These are built-in functions, enabled in YAML configuration, that performs some additional post-processing on rendered license headers, for example to update years in copyright statements.