Configuration#

While the API supports using a dict, it is still recommended to use a configuration file. The CLI requires a configuration file. The TOML file format is used to configure several things. The snippet below can be used as a template for a quick start.

[jinja]
select = ["foo.txt", "*.zip"]
select-mode = ["exclude"]

[debug]
generate-metadata-file = true

[debug.metadata-add]
foo = "foo"
bar = "bar"

[cli]
log-level = 2

[default-variables]
baz = "baz"
foobar = "foobar"

Sections#

The jinja section#

[jinja]

This section controlls the jinja template engine and which files use it.

The select option#

array<string>

select = []

By default all non-binary files are assumed to use the jinja template unless the first line is {# nojinja #}. Note that a file starting with {# nojinja #} or {# isjinja #} always overrides this option for that file. When this is set, select-mode should also be defined.

All files matching one of the glob patterns will be rendered using the jinja template engine.

The select-mode option#

"include"|"exclude" ("include")

select-mode = "include"

When this is include all files matching one of the patterns in select are marked as using the jinja# template. The opposite is the case when this option is set to exclude.

The prompt-missing option#

boolean (true)

prompt-missing = true

Prompts the user for a string when some variable is nowhere provided.

The jinja.configure section#

[jinja.configure]

This section allows you to configures jinja itself. There are currently no options but this might change in the future.

The fs section#

[fs]

The select option#

array<string>

select = []

There is usually no reason to exclude files in a template directory: just remove the files from that directory. An exception might be for a README file.

The select-mode option#

"include"|"exclude" ("include")

select-mode = "include"

The file-pattern-style option#

"glob"|"regex" ("glob")

file-pattern-style = "glob"

The pattern style to use for filtering files in the select options.

The debug section#

[debug]

The generate-metadata-file option#

boolean (false)

generate-metadata-file = false

Whether the .dirtem metadata file in the build directory should be generated. This file contains data about when the build was made, which version of dirtem was used and more information.

The debug.metadata-add section#

[debug.metadata-add]

Arbitrary key/value pairs that will be added to the .dirtem metadata file.

The cli section#

[cli]

The default-variables section#

[default-variables]

Key/Value pairs of variables that will be used when one is not provided when building.