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