From 535923e0a2a6e1eae9ba96baf3d590e938592bba Mon Sep 17 00:00:00 2001 From: Michele Cereda Date: Thu, 12 May 2022 23:24:04 +0200 Subject: [PATCH] Added yadm's notes to the knowledge base --- knowledge base/yadm.md | 96 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 knowledge base/yadm.md diff --git a/knowledge base/yadm.md b/knowledge base/yadm.md new file mode 100644 index 0000000..7cc06cc --- /dev/null +++ b/knowledge base/yadm.md @@ -0,0 +1,96 @@ +# YADM + +Yet Another Dotfile Manager. + +## TL;DR + +```shell +# Create a new repository. +yadm init \ + && yadm add .gitconfig \ + && yadm commit \ + && yadm remote add origin git@gitlab.com:user/dotfiles.git \ + && yadm push -u origin main + +# Restore an existing remote repository. +yadm clone git@gitlab.com:user/dotfiles.git \ + && yadm reset --hard HEAD \ + && yadm status + +# Set git config values. +yadm gitconfig user.email username@email.coom +yadm gitconfig user.name 'User Name' + +# Set a local class on the host. +yadm config local.class 'Work' +``` + +## Class and overrides + +_Class_ is a special value stored **locally** on each host (inside the local repository). To use alternate symlinks using `##class.`, one must set the value of _Class_ in the `local.class` setting: + +```shell +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` respectively. + +## Alternate files + +Check the official docs on [alternate files] for the updated information. + +`yadm` will automatically create a symbolic link to the appropriate version of a file when its filename is appended a valid suffix. The suffix contains the conditions that must be met for that file to be used, and is `##` followed by any number of conditions separated by commas, like `.zshrc##[,,…]`. + +Each condition is an attribute/value pair separated by a period, like `os.Darwin`. 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. + +Attribute | Description +-----------------|------------ +`template`, `t` | Valid when the value matches a supported template processor. See the [Templates](#templates) section for more details +`user`, `u` | Valid if the value matches the current user. The current user is calculated by running `id ‑u ‑n` on the host +`distro`, `d` | Valid if the value matches the distro. The distro is calculated by running `lsb_release ‑si`; if `lsb_release` is not available, the value will be **the ID** specified in the `/etc/os-release` file +`os`, `o` | Valid if the value matches the OS. The OS is calculated by running `uname ‑s` on Unix systems; the OS for Windows Subsystem for Linux is reported as _WSL_ even though uname identifies as "Linux", and the OS for Linux-like runtimes for Windows (e.g. MinGW, Cygwin) is obtained by running `uname -o` +`class`, `c` | Valid if the value matches the `local.class` configuration. The Class must be manually set using `yadm config local.class ` +`hostname`, `h` | Valid if the value matches the **short** hostname. The hostname is calculated by running `uname ‑n` and trimming off any domain +`default` | Valid when no other alternate is valid +`extension`, `e` | A special condition that doesn't affect the selection process; its purpose is instead to allow the alternate file to end with a certain extension to e.g. make editors highlight the content properly + +One may use any number of conditions, in any order. An alternate file will only be used if **ALL** conditions are met. For all files: + +- managed by `yadm`'s repository, or +- listed in `$HOME/.config/yadm/encrypt` + +symbolic links will be created for the most appropriate version if they match this naming convention. + +The _most appropriate_ version of a file is determined by calculating a score for each version of it: + +- a template **is always scored higher than any symlink condition** +- files with more conditions **will always be favored** +- any invalid condition will disqualify that file completely + +If one doesn't care to have all versions of alternates stored in the same directory as the generated symlink, one 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 no `##default` version exists and no files have valid conditions, 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 the links by default. This behaviour can be disabled using the `yadm.auto-alt` setting. Even if disabled, links can be manually created by running `yadm alt`: + +```shell +# force (re)creation of links based on alternate files +yadm alt +``` + +## Templates + +Check the official docs on [templates] for the updated information. + +## Further readings + +- the project's [homepage] +- [Alternate files] +- [Templates] + +[homepage]: https://yadm.io/ + +[alternate files]: https://yadm.io/docs/alternates +[templates]: https://yadm.io/docs/templates