parent
eec6d49f98
commit
392a66829a
@ -0,0 +1,102 @@
|
|||||||
|
---
|
||||||
|
title: "Templates"
|
||||||
|
permalink: /docs/templates
|
||||||
|
---
|
||||||
|
Templates are a special kind of [alternate](/docs/alternates) 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>
|
||||||
|
|
||||||
|
<sub>
|
||||||
|
"template" can also be shortened to "t".
|
||||||
|
</sub>
|
||||||
|
|
||||||
|
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. |
|
||||||
|
|
||||||
|
<sub>
|
||||||
|
The processor can be omitted for "default".
|
||||||
|
Also, `j2` will be processed by either j2cli or envtpl, whichever is found.
|
||||||
|
</sub>
|
||||||
|
|
||||||
|
## 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 | <code>yadm config local.class</code> |
|
||||||
|
| `yadm.distro` | `YADM_DISTRO` | Distribution | <code>lsb_release ‑si</code> |
|
||||||
|
| `yadm.hostname` | `YADM_HOSTNAME` | Hostname | `hostname` (without domain) |
|
||||||
|
| `yadm.os` | `YADM_OS` | Operating system | <code>uname ‑s</code> |
|
||||||
|
| `yadm.user` | `YADM_USER` | Current user | <code>id ‑u ‑n</code> |
|
||||||
|
| `yadm.source` | `YADM_SOURCE` | Template filename | (fully qualified path) |
|
||||||
|
|
||||||
|
## 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][j2cli] (or `j2`) is a Python-based Jinja2 template processor. This
|
||||||
|
fully supports all directives of the [Jinja2 library][jinja]. When your template is
|
||||||
|
processed, the YADM_* values are provided to j2cli as environment variables.
|
||||||
|
|
||||||
|
envtpl
|
||||||
|
: [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:
|
||||||
|
|
||||||
|
```jinja
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
```jinja
|
||||||
|
{% if yadm.os == "Darwin" %}
|
||||||
|
This block is included for MacOS
|
||||||
|
{% else %}
|
||||||
|
This block is included for for any other OS
|
||||||
|
{% endif %}
|
||||||
|
```
|
||||||
|
|
||||||
|
{% endraw %}
|
||||||
|
|
||||||
|
[envtpl]: https://github.com/andreasjansson/envtpl
|
||||||
|
[j2cli]: https://github.com/kolypto/j2cli
|
||||||
|
[jinja]: https://jinja.palletsprojects.com
|
@ -0,0 +1,35 @@
|
|||||||
|
---
|
||||||
|
title: "Hooks"
|
||||||
|
permalink: /docs/hooks
|
||||||
|
---
|
||||||
|
For every command yadm supports, a program can be provided to run before or
|
||||||
|
after that command. These are referred to as "hooks". yadm looks for hooks in
|
||||||
|
the directory
|
||||||
|
`$HOME/.config/yadm/hooks`.
|
||||||
|
Each hook is named using a prefix of `pre_` or `post_`, followed by the command
|
||||||
|
which should trigger the hook. For example, to create a hook which is run after
|
||||||
|
every `yadm pull` command, create a hook named `post_pull`.
|
||||||
|
Hooks must have the executable file permission set.
|
||||||
|
|
||||||
|
If a `pre_` hook is defined, and the hook terminates with a non-zero exit
|
||||||
|
status, yadm will refuse to run the yadm command. For example, if a
|
||||||
|
`pre_commit` hook is defined, but that command ends with a non-zero exit status,
|
||||||
|
the `yadm commit` will never be run. This allows one to "short-circuit" any
|
||||||
|
operation using a `pre_` hook.
|
||||||
|
|
||||||
|
Hooks have the following environment variables available to them at runtime:
|
||||||
|
|
||||||
|
YADM_HOOK_COMMAND
|
||||||
|
: The command which triggered the hook
|
||||||
|
|
||||||
|
YADM_HOOK_EXIT
|
||||||
|
: The exit status of the yadm command
|
||||||
|
|
||||||
|
YADM_HOOK_FULL_COMMAND
|
||||||
|
: The yadm command with all command line arguments
|
||||||
|
|
||||||
|
YADM_HOOK_REPO
|
||||||
|
: The path to the yadm repository
|
||||||
|
|
||||||
|
YADM_HOOK_WORK
|
||||||
|
: The path to the work-tree
|
@ -0,0 +1,61 @@
|
|||||||
|
---
|
||||||
|
title: "Upgrading from Version 1"
|
||||||
|
permalink: /docs/upgrade_from_1
|
||||||
|
---
|
||||||
|
|
||||||
|
Beginning with version 2.0.0, yadm introduced a few major changes which may
|
||||||
|
require you to adjust your configurations.
|
||||||
|
|
||||||
|
If you want to retain yadm's old behavior until you transition your
|
||||||
|
configurations, you can set an environment variable `YADM_COMPATIBILITY=1`.
|
||||||
|
Doing so will automatically use the old yadm directory, and process alternates the same as version 1.
|
||||||
|
This compatibility mode is deprecated, and will be removed in future versions.
|
||||||
|
This mode exists solely for transitioning to the new paths and naming of alternates.
|
||||||
|
|
||||||
|
## New yadm directory location
|
||||||
|
yadm now uses the [XDG Base Directory Specification][xdg-spec] to find its configurations.
|
||||||
|
For the majority of users, this means configurations will now be in
|
||||||
|
`$HOME/.config/yadm` instead of the old location of `$HOME/.yadm`.
|
||||||
|
|
||||||
|
You can customize the base directory by specifying an environment variable
|
||||||
|
named `XDG_CONFIG_HOME`.
|
||||||
|
|
||||||
|
If you previously had configurations in `$HOME/.yadm`, the easiest way
|
||||||
|
to migrate is to use the new `yadm upgrade` command. This command will move your
|
||||||
|
existing repo and configurations to the new directory, and rename any yadm
|
||||||
|
configurations that are tracked by your repo.
|
||||||
|
|
||||||
|
## New alternate file naming convention
|
||||||
|
The naming conventions for alternate files have been changed.
|
||||||
|
Read full details about the new naming convention [here](/docs/alternates).
|
||||||
|
|
||||||
|
This table of examples should help you understand how to translate old filenames
|
||||||
|
to new ones.
|
||||||
|
|
||||||
|
| Conditions | Old suffix | New suffix |
|
||||||
|
| - | - | - |
|
||||||
|
| Default file | `##` | `##default` |
|
||||||
|
| MacOS host | `##Darwin` | `##o.Darwin` |
|
||||||
|
| yadm.class = "work" | `##work` | `##c.work` |
|
||||||
|
| Linux host named "dromio" | `##Linux.dromio` | `##o.Linux,h.dromio` |
|
||||||
|
| Linux host named "dromio" with user named "antipholus" | `##Linux.dromio.antipholus` | `##o.Linux,h.dromio,u.antipholus` |
|
||||||
|
| Host named "luciana" | `##%.luciana` | `##h.luciana` |
|
||||||
|
| Any Linux host with user named "egeon" | `##Linux.%.egeon` | `##o.Linux,u.egeon` |
|
||||||
|
| User named "balthazar" | `##%.%.balthazar` | `##u.balthazar` |
|
||||||
|
| A Jinja template | `##yadm.j2` | `##template.j2` |
|
||||||
|
|
||||||
|
## Built-in template processing
|
||||||
|
Older versions supported Jinja templates if envtpl was installed. New versions
|
||||||
|
support _multiple_ template processors, including a built-in processor. The
|
||||||
|
built-in processor has a limited feature set, but should be sufficient for most
|
||||||
|
users needs (without having to install additional software). Read full details
|
||||||
|
[here](/docs/templates).
|
||||||
|
|
||||||
|
## Option `yadm.cygwin-copy` changed to `yadm.alt-copy`
|
||||||
|
Older versions supported a `yadm.cygwin-copy` option, because some software
|
||||||
|
doesn't work well with CYGWIN symlinks. Now that option has been renamed to
|
||||||
|
`yadm.alt-copy`, and can be used on any system, not just CYGWIN. So if you have
|
||||||
|
a system which doesn't fully support symlinks, you can have alternates created
|
||||||
|
as files instead.
|
||||||
|
|
||||||
|
[xdg-spec]: https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
|
After Width: | Height: | Size: 10 KiB |
After Width: | Height: | Size: 8.8 KiB |
After Width: | Height: | Size: 7.5 KiB |
After Width: | Height: | Size: 6.0 KiB |
Loading…
Reference in new issue