yadm/_docs/070_templates.md

title	permalink
Templates	/docs/templates

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)
esh	##template.esh	esh must be installed.
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 or ESH	Description	Source
yadm.class	YADM_CLASS	Locally defined yadm class	yadm config local.class
yadm.distro	YADM_DISTRO	Distribution	lsb_release ‑si or /etc/os-release
yadm.hostname	YADM_HOSTNAME	Hostname	uname ‑n (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)

<sub><sup>* The OS for "Windows Subsystem for Linux" is reported as "WSL", even though uname identifies as "Linux".
* If lsb_release is not available, "distro" will be the ID specified in /etc/os-release.</sup></sub>

Supported template processors

default

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.

esh

esh is a template processor written in POSIX compliant shell. It allows executing shell commands within templates. This can be used to reference your own configurations within templates.

j2cli

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

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.

{% raw %}

variables

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 }}

if-else-endif

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 any other OS
{% endif %}

include

Content can be included from external files using the {% include "filename" %} syntax. The filename may include variables and should be either a path relative to the current template or an absolute path. The included file may itself also use variables, but if-else-endif or include directives are not supported. An example:

{% include "extra/config.{{ yadm.os }}" %}

{% endraw %}