The !include directive

Stack's configuration files are in the YAML format. Stack also supports the use of an !include local tag together with scalar content that represents an absolute or relative path to another file. This provides a directive that allows the content of one YAML file to be included in another.

The directive can be used in both project-level and global configuration files.

Note

An included relative file path is relative to the directory containing the file with the !include directive.

Warning

The stack config set commands cannot modify a configuration file that excludes the relevant key and uses !include directives.

Including a value

A value for a key can be provided by an included file. For example, given a file snapshot.yaml in the project directory with the content:

lts-24.43

the following project-level configuration file would use lts-24.43 as the snapshot:

snapshot: !include snapshot.yaml

The included file replaces the !include directive with its content, so this is equivalent to:

snapshot: lts-24.43

Including a sequence

The value provided by an included file is not limited to scalar content. It can be a YAML sequence. For example, given a file extra-deps.yaml in the project directory with the content:

- acme-missiles-0.3
- text-short-0.1.6

the following project-level configuration file would use those as extra-deps:

snapshot: lts-24.43
extra-deps: !include extra-deps.yaml

Merging mappings

YAML's merge key (<<) is used to indicate that all of the keys of one or more specified mappings should be inserted into the current mapping.

YAML's merge key can be combined with an !include directive to merge the content of an included file into the current mapping. For example, given a file shared-config.yaml in the project directory with the content:

ghc-options:
  "$everything": -Wall
flags:
  my-package:
    my-flag: true

the following project-level configuration file would merge those options:

snapshot: lts-24.43
<<: !include shared-config.yaml

This is equivalent to:

snapshot: lts-24.43
ghc-options:
  "$everything": -Wall
flags:
  my-package:
    my-flag: true

The !include directive can also be placed on the line after the merge key:

snapshot: lts-24.43
<<:
  !include shared-config.yaml

Nested includes

Included files can themselves contain !include directives, allowing for nested composition of configuration.

Note

A file cannot include itself or a file that has already included the file. Stack detects and raises an error for cyclic includes.