diff --git a/_data/navigation.yml b/_data/navigation.yml index 8d0a90b..ab033fd 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -31,10 +31,16 @@ docs: url: /docs/bootstrap - title: "Alternate Files" url: /docs/alternates + - title: "Templates" + url: /docs/templates - title: "Encryption" url: /docs/encryption + - title: "Hooks" + url: /docs/hooks - title: More Help children: + - title: "Upgrading from Version 1" + url: /docs/upgrade_from_1 - title: "FAQ" url: /docs/faq - title: "Example Dotfiles" diff --git a/_docs/035_common_usage.md b/_docs/035_common_usage.md index 6de2dd3..e3b871c 100644 --- a/_docs/035_common_usage.md +++ b/_docs/035_common_usage.md @@ -45,11 +45,11 @@ current directory or below. Read about [alternate files](alternates) for more details. `yadm encrypt` -: Encrypt all files matching the patterns found in `$HOME/.yadm/encrypt`. Read +: Encrypt all files matching the patterns found in `$HOME/.config/yadm/encrypt`. Read about [encryption](encryption) for more details. `yadm decrypt`, `yadm decrypt -l` -: Decrypt files stored in `$HOME/.yadm/files.gpg`. Using the `-l` option will +: Decrypt files stored in `$HOME/.config/yadm/files.gpg`. Using the `-l` option will only list the files (without decrypting them). Read about [encryption](encryption) for more details. diff --git a/_docs/037_bootstrap.md b/_docs/037_bootstrap.md index f122a96..a4b056c 100644 --- a/_docs/037_bootstrap.md +++ b/_docs/037_bootstrap.md @@ -13,14 +13,14 @@ perform, yadm has a standard command for executing them. yadm bootstrap -This command will execute the program named `$HOME/.yadm/bootstrap`. You must +This command will execute the program named `$HOME/.config/yadm/bootstrap`. You must provide this program yourself, and it must be made executable. But those are the only constraints. After yadm successfully clones a repository, if there is a bootstrap program available, it will offer to run it for you. - Found .yadm/bootstrap + Found .config/yadm/bootstrap It appears that a bootstrap program exists. Would you like to execute it now? (y/n) diff --git a/_docs/040_alternates.md b/_docs/040_alternates.md index 016aa27..09c6aa6 100644 --- a/_docs/040_alternates.md +++ b/_docs/040_alternates.md @@ -10,130 +10,107 @@ features and strategies for dealing with those occasions. ## Symlink alternates It can be useful to have an automated way of choosing an alternate version of a -file for a different operating system, host, or user. yadm implements a -feature which will automatically create a symbolic link to the appropriate -version of a file, as long as you follow a specific naming convention. yadm can -detect files with names ending in: +file for a different operating system, host, user, etc. -| `##` | Default file linked | -| `##CLASS` | Matching Class | -| `##CLASS.OS` | Matching Class & OS | -| `##CLASS.OS.HOSTNAME` | Matching Class, OS & Hostname | -| `##CLASS.OS.HOSTNAME.USER` | Matching Class, OS, Hostname, & User | -| `##OS` | Matching OS | -| `##OS.HOSTNAME` | Matching OS & Hostname | -| `##OS.HOSTNAME.USER` | Matching OS, Hostname, & User | +yadm will automatically create a symbolic link to the appropriate version of a +file, when a valid suffix is appended to the filename. The suffix contains the +conditions that must be met for that file to be used. -If there are any files managed by yadm's repository, or listed in -`$HOME/.yadm/encrypt`, which match this naming convention, symbolic links will -be created for the most appropriate version. This may best be demonstrated by -example. Assume the following files are managed by yadm's repository: +The suffix begins with `##`, followed by any number of conditions separated by +commas. - $HOME/path/example.txt## - $HOME/path/example.txt##Work - $HOME/path/example.txt##Darwin - $HOME/path/example.txt##Darwin.host1 - $HOME/path/example.txt##Darwin.host2 - $HOME/path/example.txt##Linux - $HOME/path/example.txt##Linux.host1 - $HOME/path/example.txt##Linux.host2 + ##[,,…] -If running on a Macbook named `host2`, yadm will create a symbolic link which -looks like this: +Each condition is an attribute/value pair, separated by a period. Some +conditions do not require a "value", and in that case, the period and value can +be omitted. Most attributes can be abbreviated as a single letter. -`$HOME/path/example.txt` → `$HOME/path/example.txt##Darwin.host2` +| Attribute | Meaning | +| - | - | +| `template`, `t` | Valid when the value matches a supported template processor. See the [Templates](/docs/templates) section for more details.| +| `user`, `u` | Valid if the value matches the current user. Current user is calculated by running id ‑u ‑n. | +| `distro`, `d` | Valid if the value matches the distro. Distro is calculated by running lsb_release ‑si. | +| `os`, `o` | Valid if the value matches the OS. OS is calculated by running uname ‑s. | +| `class`, `c` | Valid if the value matches the local.class configuration. Class must be manually set using yadm config local.class <class>. | +|`hostname`, `h`|Valid if the value matches the short hostname. Hostname is calculated by running `hostname`, and trimming off any domain.| +|`default`|Valid when no other alternate is valid.| -However, on another Macbook named `host3`, yadm will create a symbolic link -which looks like this: +You may use any number of conditions, in any order. An alternate will only be +used if _ALL_ conditions are valid. For all files managed by yadm's repository +or listed in `$HOME/.config/yadm/encrypt`, if they match this naming convention, +symbolic links will be created for the most appropriate version. -`$HOME/path/example.txt` → `$HOME/path/example.txt##Darwin` +The "most appropriate" version is determined by calculating a score for each +version of a file. A [template](/docs/templates) is always scored higher than +any symlink condition. The number of conditions is the next largest factor in +scoring. Files with more conditions will always be favored. Any invalid +condition will disqualify that file completely. -Since the host name doesn't match any of the managed files, the more generic -version is chosen. +If you don't care to have all versions of alternates stored in the same +directory as the generated symlink, you can place them in the +`$HOME/.config/yadm/alt` directory. The generated symlink or processed template +will be created using the same relative path. -If running on a Linux server named `host4`, the link will be: +Alternate linking may best be demonstrated by example. Assume the following +files are managed by yadm's repository: -`$HOME/path/example.txt` → `$HOME/path/example.txt##Linux` + $HOME/path/example.txt##default + $HOME/path/example.txt##class.Work + $HOME/path/example.txt##os.Darwin + $HOME/path/example.txt##os.Darwin,hostname.host1 + $HOME/path/example.txt##os.Darwin,hostname.host2 + $HOME/path/example.txt##os.Linux + $HOME/path/example.txt##os.Linux,hostname.host1 + $HOME/path/example.txt##os.Linux,hostname.host2 -If running on a Solaris server, the link use the default `##` version: +If running on a Macbook named `host2`, yadm will create a symbolic link which looks like this: -`$HOME/path/example.txt` → `$HOME/path/example.txt##` +`$HOME/path/example.txt` → `$HOME/path/example.txt##os.Darwin,hostname.host2` -If running on a system, with `CLASS` set to "Work" ([see below](alternates#class-and-overrides)), the link will be: +However, on another Mackbook named `host3`, yadm will create a symbolic link which looks like this: -`$HOME/path/example.txt` → `$HOME/path/example.txt##Work` +`$HOME/path/example.txt` → `$HOME/path/example.txt##os.Darwin` -If no `##` version exists and no files match the current CLASS/OS/HOSTNAME/USER, -then no link will be created. +Since the hostname doesn't match any of the managed files, the more generic +version is chosen. If running on a Linux server named `host4`, the link will be: -| **CLASS** must be manually set using `yadm config local.class `. -| **OS** is determined by running `uname -s`. -| **HOSTNAME** by running `hostname` and removing any domain. -| **USER** by running `id -u -n`. +`$HOME/path/example.txt` → `$HOME/path/example.txt##os.Linux` -yadm will automatically create these links by default. This can be disabled using the `yadm.auto-alt` configuration. Even if disabled, links can be manually created by running yadm alt. +If running on a Solaris server, the link will use the default version: -## Wildcards +`$HOME/path/example.txt` → `$HOME/path/example.txt##default` -It is possible to use `%` as a "wildcard" in place of `CLASS`, `OS`, `HOSTNAME`, -or `USER`. For example, The following file could be linked for *any host* when the -user is "harvey". +If running on a system, with class set to `Work`, the link will be: -``` -$HOME/path/example.txt##%.%.harvey -``` +`$HOME/path/example.txt` → `$HOME/path/example.txt##class.Work` + +If no `##default` version exists and no files have valid conditions, then no +link will be created. + +Links are also created for directories named this way, as long as they have at +least one yadm managed file within them. + +yadm will automatically create these links by default. This can be disabled +using the `yadm.auto-alt` configuration. Even if disabled, links can be manually +created by running `yadm alt`. ## Class and Overrides Class is a special value which is stored locally on each host (inside the local -repository). To use alternate symlinks using `CLASS`, you must set the value of -class using the configuration `local.class`. This is set like any other yadm -configuration—with the `yadm config` command. The following sets the `CLASS` to -be "Work". +repository). To use alternate symlinks using `##class.`, you must set the +value of class using the configuration `local.class`. This is set like any other +yadm configuration—with the `yadm config` command. The following sets the +`local.class` to be "Work". yadm config local.class Work -Similarly, the values of `OS`, `HOSTNAME`, and `USER` can be manually -overridden using the configuration options `local.os`, `local.hostname`, and -`local.user`. +Similarly, the values of `os`, `hostname`, and `user` can be manually overridden +using the configuration options `local.os`, `local.hostname`, and `local.user`. -## Jinja templates +## Templates -If the `envtpl` command is available, Jinja templates will also be processed to -create or overwrite real files. yadm will treat files ending in `##yadm.j2` -as Jinja templates. During processing, the following variables are set according -to the rules explained in the [Alternates section](alternates#symlink-alternates): - -* `YADM_CLASS` -* `YADM_OS` -* `YADM_HOSTNAME` -* `YADM_USER` - -In addition `YADM_DISTRO` is exposed as the value of `lsb_release -si` if -lsb_release is locally available. - -For example, a file named `whatever##yadm.j2` with the following content - - {% raw %} - {% if YADM_USER == 'harvey' -%} - config={{YADM_CLASS}}-{{ YADM_OS }} - {% else -%} - config=dev-whatever - {% endif -%} - {% endraw %} - -would write a file named `whatever` with the following content if the user is -"harvey": - - config=work-Linux - -and the following otherwise: - - config=dev-whatever - -See [andreasjansson/envtpl](https://github.com/andreasjansson/envtpl) for more information about -`envtpl`, and see [jinja.pocoo.org](http://jinja.pocoo.org/) for an overview of -Jinja. +Templates are another powerful tool for creating alternate content on each host. +See the [Templates](/docs/templates) documentation for full details. ## Strategies for alternate files on different systems diff --git a/_docs/045_templates.md b/_docs/045_templates.md new file mode 100644 index 0000000..655bc4b --- /dev/null +++ b/_docs/045_templates.md @@ -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.