Templates are a special kind of alternate file. The template content and host specific data are combined as input to a template processor which produces a new file as its output.

This can be very useful if you need to vary a small part of a file, but it doesn’t support any kind of include directive.

Template suffixes

To create a template, append an alternate suffix to the file name. The suffix has the format:

##template.<template processor>

“template” can also be shortened to “t”.

The supported template processors are:

Processor Suffixes Dependencies
default ##template, ##template.default awk must be installed. (This should be installed on all *nix systems)
j2cli ##template.j2, ##template.j2cli j2cli must be installed.
envtpl ##template.j2, ##template.envtpl envtpl must be installed.

The processor can be omitted for “default”. Also, j2 will be processed by either j2cli or envtpl, whichever is found.

Exposed data

When template processors run, they will be provided the following set of data.

Default (built-in) Jinja Description Source
yadm.class YADM_CLASS Locally defined yadm class yadm config local.class
yadm.distro YADM_DISTRO Distribution lsb_release ‑si
yadm.hostname YADM_HOSTNAME Hostname hostname (without domain)
yadm.os YADM_OS Operating system uname ‑s *
yadm.user YADM_USER Current user id ‑u ‑n
yadm.source YADM_SOURCE Template filename (fully qualified path)

* The OS for “Windows Subsystem for Linux” is reported as “WSL”, even though uname identifies as “Linux”.

Supported template processors

This built-in processor requires no additional software (assuming your distro contains awk). This processor has a syntax similar to the Jinja processors below, however it only supports a small set of directives. Those directives are detailed in the section below.
j2cli (or j2) is a Python-based Jinja2 template processor. This fully supports all directives of the Jinja2 library. When your template is processed, the YADM_* values are provided to j2cli as environment variables.
envtpl is another Python-based Jinja2 template processor. Online comments suggest this software might not be maintained anymore.

Built-in directives

yadm’s “default” (built-in) template processor supports the following directives.

Variables should be surrounded by {{ }}. It is fine for there to be whitespace between the variable name and the double braces. The {{ and }} must be on the same line. For example:
# WARNING: Do not edit this file.
# It was generated by processing {{ yadm.source }}
Entire blocks of content can be included or excluded based on the value of a variable. Only equality can be tested. These blocks must start with {% if yadm.variable == "value" %} and end with {% endif %}. An alternative block can also be specified using the directive {% else %}. These directives must appear on lines by themselves. They may not appear on the same line. The “if” directive only supports testing a single variable, and there is no “elif” directive as there is in Jinja. Here is an example.
{% if yadm.os == "Darwin" %}
This block is included for MacOS
{% else %}
This block is included for for any other OS
{% endif %}