From 2f95fca1c4f96195b243ea66baaf35b8b3e750b9 Mon Sep 17 00:00:00 2001 From: Tim Byrne Date: Tue, 31 Jan 2017 17:29:45 -0600 Subject: [PATCH] Update web documentation for alternates --- _docs/040_alternates.md | 55 +++++++++++++++++++++++++++++++++-------- 1 file changed, 45 insertions(+), 10 deletions(-) diff --git a/_docs/040_alternates.md b/_docs/040_alternates.md index 589d47e..29d57dd 100644 --- a/_docs/040_alternates.md +++ b/_docs/040_alternates.md @@ -15,10 +15,14 @@ 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: -| `##` | Default file linked | -| `##OS` | Matching OS | -| `##OS.HOSTNAME` | Matching OS & Hostname | -| `##OS.HOSTNAME.USER` | Matching OS, Hostname, and User | +| `##` | 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 | If there are any files managed by **yadm**'s repository, or listed in `$HOME/.yadm/encrypt`, which match this naming convention, symbolic links will @@ -26,6 +30,7 @@ be created for the most appropriate version. This may best be demonstrated by example. Assume the following files are managed by **yadm**'s repository: $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 @@ -43,7 +48,7 @@ which looks like this: `$HOME/path/example.txt` → `$HOME/path/example.txt##Darwin` -Since the hostname doesn't match any of the managed files, the more generic +Since the host name 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: @@ -54,13 +59,43 @@ If running on a Solaris server, the link use the default `##` version: `$HOME/path/example.txt` → `$HOME/path/example.txt##` -If no `##` version exists and no files match the current OS/HOST- NAME/USER, +If running on a system, with `CLASS` set to "Work" ([see below](alternates#class-and-overrides)), the link will be: + +`$HOME/path/example.txt` → `$HOME/path/example.txt##Work` + +If no `##` version exists and no files match the current CLASS/OS/HOSTNAME/USER, then no link will be created. -| OS is determined by running `uname -s`, HOSTNAME by running `hostname -s`, and -USER by running `id -u -n`. **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** 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`. + +**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. + +## Wildcards + +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". + +``` +$HOME/path/example.txt##%.%.harvey +``` + +## 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". + + 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`. ## Strategies for alternate files on different systems