4.4 KiB
| 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) |
| 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
- 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. - 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 for any other OS
{% endif %}
{% endraw %}