Alternate Files

When possible, it is best to use the same files across all systems. However, there are occasions when you need different files in some places. Below are features and strategies for dealing with those occasions.

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:

## 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 be created for the most appropriate version. This may best be demonstrated by example. Assume the following files are managed by yadm’s repository:


If running on a Macbook named host2, yadm will create a symbolic link which looks like this:


However, on another Macbook named host3, yadm will create a symbolic link which looks like this:


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:


If running on a Solaris server, the link use the default ## version:


If running on a system, with CLASS set to “Work” (see below), the link will be:


If no ## version exists and no files match the current CLASS/OS/HOSTNAME/USER, then no link will be created.

CLASS must be manually set using yadm config local.class <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 configuration. Even if disabled, links can be manually created by running yadm alt.


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”.


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.

Jinja 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:


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

{% if YADM_USER == 'harvey' -%}
config={{YADM_CLASS}}-{{ YADM_OS }}
{% else -%}
{% endif -%}

would write a file named whatever with the following content if the user is “harvey”:


and the following otherwise:


See andreasjansson/envtpl for more information about envtpl, and see for an overview of Jinja.

Strategies for alternate files on different systems

Where possible, you should try to use the same file on every system. Here are a few examples:


let OS=substitute(system('uname -s'),"\n","","")
if (OS == "Darwin")
    " do something that only makes sense on a Mac


# use reattach-to-user-namespace as the default command on OSX
if-shell "test -f /usr/local/bin/reattach-to-user-namespace" 'set -g default-command "reattach-to-user-namespace -l bash"'


system_type=$(uname -s)
if [ "$system_type" = "Darwin" ]; then
    eval $(gdircolors $HOME/.dir_colors)
    eval $(dircolors -b $HOME/.dir_colors)


However, sometimes the type of file you are using doesn’t allow for this type of logic. If a configuration can do an “include”, you can include a specific alternate version using yadm. Consider these three files:


    decorate = short
    abbrevCommit = true
    path = .gitconfig.local


    name = Tim Byrne
    email =


    name = Dr. Tim Byrne
    email =

Configuring Git this way includes .gitconfig.local in the standard .gitconfig. yadm will automatically link the correct version based on the operating system. The bulk of your configurations can go in a single file, and you just put the exceptions in OS-specific files.