Getting started

Remember: Yolk is currently in very early development. Expect some breakages and issues. Always have a good backup of your files before using Yolk in this stage. You have been warned.

How dotfiles are stored

Yolk manages your dotfiles by storing them in a separate directory, typically inside ~/.config/yolk. This allows you to keep your dotfiles in version control easily, and lets you manage your configuration from one central location.

Yolk groups dotfiles into so-called "eggs", which are packages of configuration, typically for one single application (although you can group them however you want, or even just have one egg for all your configuration files).

When an egg is "deployed", Yolk creates symlinks in the target location pointing towards the egg directory. This way, the configured appliactions will see the configuration files as they expect to see them.

To define where a set of configuration files should be deployed to, you declare each of your eggs in your main yolk configuration file. This allows you, among other things, to define a different target directory per system.

Initial setup

To get started with Yolk, you'll first need to set up the Yolk file structure.

$ yolk init

This will create the yolk directory, with a default yolk.rhai file, and an eggs directory.

Adding your first egg

let's say we want to manage the configuration for the alacritty terminal emulator. To do this, we first move our alacritty configuration into the eggs directory:

$ mv ~/.config/alacritty ~/.config/yolk/eggs/

And then configure the corresponding egg deployment:

export let eggs = #{
    alacritty: #{
        targets: "~/.config/alacritty",
        templates: ["alacritty.yml"],
        enabled: true,
    }
}

Now we can run yolk sync! This will set up a symlink from the target location ~/.config/alacritty back to the alacritty egg directory ~/.config/yolk/eggs/alacritty.

Committing your dots to git

Now, we want to make sure our dotfiles are in version control and pushed to our git host of choice. Every interaction with git should be done through the yolk git command. This ensures that git sees the canonical (stable) representation of your files, and automatically performs them from within the yolk directory.

$ yolk git init
$ yolk safeguard
$ yolk git add --all
$ yolk git commit -m "Setup alacritty"

To understand what yolk safeguard does, see safeguarding git.

You can now set up your git reomte and use git as usual -- just remember to always use yolk git, especially when you're committing your files.

Baby's first template

Because you too are very indecisive about your terminal colors, you now decide you want to use yolk to manage your color theme for alacritty, and any other applications that you might add later. You also decide that you want to use a different color scheme on your desktop and your laptop.

To achieve this, let's first add a declaration of your color theme in your ~/.config/yolk/yolk.rhai file:

// ... snip ...

const themes = #{
    gruvbox: #{
        background: "#282828",
        foreground: "#ebdbb2",
    },
    mono: #{
        background: "#000000",
        foreground: "#ffffff",
    },
}

export const data = #{
    colors = if SYSTEM.hostname == "laptop" { themes.gruvbox } else { themes.mono }
}

Beautiful! What we're doing here is setting up an exported table called data, which will store any user-data we might want to refer to in our templates in the future. We set up a field colors, which we then set to a different color scheme depending on the hostname of the system.

Don't forget to export any variables you might want to reference in your template tags!

Now, let's set up a template in our alacritty config file:

#...
[colors.primary]
background = "#ff0000" # {< replace_color(data.colors.background) >}
foreground = "#ff0000" # {< replace_color(data.colors.foreground) >}
# ...

Let's break down what's happening here: Inside the comments after the color declarations, we're using "inline template tags", as indicated by the {< ... >} syntax. These inline tags transform whatever is before them in the line. The tag calls the built-in replace_color function, which looks for a hex-code and replaces it with the value from the data.colors table.

Let's try it! Run

$ yolk sync

You will see that, your alacritty.toml has changed, and the colors from your yolk.rhai file have been applied, depending on your hostname.

Git concepts

Basic familiarity with git is assumed.

Safeguarding git

Yolk wraps the git CLI to ensure that git only ever interacts with your dotfiles in their canonical state. If it didn't do that, you would end up committing the local state of your dotfiles, which would conflict with their state from another machine -- which is what yolk is trying to solve.

To ensure that you're not accidentally using the regular git CLI for your dotfiles, it is recommended to "safeguard" your dotfiles' git directory. To do this, simply run

$ yolk safeguard

after cloning or initializing your dotfiles.

This simply renames the .git directory to .yolk_git, which means the regular git CLI won't see the repository anymore. You are now more or less forced to use the yolk git command instead -- which conveniently doesn't just ensure consistency of the git state, but also works from anywhere in your filesystem!

Cloning your dotfiles

To clone your dotfiles on a new machine, simply clone the repository to .config/yolk, and safeguard your git directory.

$ git clone <your-dots-repo> "$XDG_CONFIG_HOME/yolk"
$ yolk safeguard

After that, you can start yolk syncing your eggs!

Interacting with git

To stage or commit changes, get the git diff or status, you can use the yolk git command, which behaves just like the git CLI. So, instead of

git status, you run yolk git status,
git add ., you run yolk git add --all,
git commit -m "cool changes", you run yolk git commit -m "cool changes,

and so on. This ensures the files are always in the correct canonical state, and makes it possible to interact with a safeguarded git repository.

Eggs

An egg is one package of configuration, typically for one single application. For example, your editor configuration ~/.config/nvim would likely be one egg called nvim.

According to your yolk.rhai, these get deployed on your system, and may contain some templated files.

Templates in Yolk

Yolk allows you to use simple templates directly within your config files. Those templates will be evaluated whenever you run yolk sync or interact with git (see Git concepts).

Expressions within these templates are written in the Rhai scripting language, and have access to a couple special variables that allow you to reference your configuration and system state.

There are two main kinds of templates in Yolk: conditional templates and template tag functions.

Preparation

To make yolk evaluate your file as a template, you need to explicitly tell yolk about it. To do this, make sure you include it in the templates list of your eggs deployment configuration in your yolk.rhai:

export let eggs = #{
  foo: {
    targets: "~/.config/foo",
    templates: ["foo.toml"],
  }
}

Conditionals

You can use Conditional template elements to conditionally include or exclude parts of your configuration. Let's take a look at a simple example:

# {% if SYSTEM.hostname == "epic-desktop" %}
displays = ["DP-1", "DP-2"]
# {% else %}
displays = ["eDP-1"]
# {% end %}

Once you run yolk sync, yolk will evaluate the condition and comment out the block that doesn't apply. For example, on your laptop, this config would be turned into:

# {% if SYSTEM.hostname == "epic-desktop" %}
#<yolk> displays = ["DP-1", "DP-2"]
# {% else %}
displays = ["eDP-1"]
# {% end %}

Template tag functions

In addition to conditionals, Yolk provides a wide variety of functions to edit your configuration, such as to insert values from, say, your color theme. These are regular rhai functions that modify their attached block of text (see below).

All of the built-in template tag functions are documented in the Rhai reference, and you can also define your own!

Different types of tags

Yolk supports three different types of tags:

Next-line tags ({# ... #}): These tags operate on the line following the tag.
Inline tags ({< ... >}): These tags operate on everything before the tag within the same line.
Block tags ({% ... %} ... {% end %}): These tags operate on everything between the tag and the corresponding {% end %} tag.

You can use whichever of these you want, wherever you want. For example, all of these do the same:

background_color = "#000000" # {< replace_color(colors.background) >}

# {# replace_color(colors.background) #}
background_color = "#000000"

# {% replace_color(colors.background) %}
background_color = "#000000"
# {% end %}

Example: Templating your color scheme

In many cases, you'll want to make specific values, such as colors or paths, be set through one central source, rather than specifying them in every config file. Yolk allows you to do this (and more) by using various template functions. For example, the replace_quoted directive takes any value and replaces whatever is in quotes with the result of the expression.

# {# replace_quoted(colors.background) #}
background_color = "#000000"
# {# replace_quoted(colors.foreground) #}
foreground_color = "#ffffff"

After running yolk sync, yolk will replace the regex patterns with the corresponding result of the Lua expression. For example, depending on how you configured your colors in your yolk.rhai, this could turn into:

# {# replace_quoted(colors.background) #}
background_color = "#282828"
# {# replace_quoted(colors.foreground) #}
foreground_color = "#ebdbb2"

Yolk will refuse to evaluate directives that are non-reversible (i.e. if you replace_red ".*" with foo, as foo will no longer match that regex pattern).

The yolk.rhai file

The yolk.rhai file is the heart of your Yolk configuration.

It's where you define all of your eggs (packages), as well as export any variables and functionality you will then refer to inside your templates.

If you're familiar with Rhai, this is loaded as a module, imported into the global scope of your template tags.

Basic structure

The yolk.rhai file is a Rhai script that is run by Yolk to generate your configuration. Everything you declare in yolk.rhai will be available to use in your templates.

Your yolk.rhai needs to define one special variable called eggs. This is a map of all the eggs you have in your egg directory, which describes where their files should be deployed to, and which files should be treated as template files.

Let's look at an example:

export let eggs = #{
    foot: #{
        targets: "~/.config/foot",
        templates: ["foot.ini"],
    },
    zsh: #{
        targets: #{
            ".zshrc": "~/.config/zsh/.zshrc",
            ".zshenv": "~/.zshenv",
        },
        main_file: ".zshrc"
    },
    nvim: #{
        targets: "~/.config/nvim",
        // Note that you can use shell-style glob patterns for the templates list
        templates: ["**/*.lua"],
    },
    niri: #{
        targets: "~/.config/niri",
        templates: ["config.kdl"],
        enabled: SYSTEM.hostname == "cool-desktop",
    },
    alacritty: "~/.config/alacritty",
    // This uses the `merge` deployment strategy, which
    // will merge the directory structures during deployment,
    // allowing a stow-style pattern
    // of mirroring your home directory structure in your egg dir
    zed: { targets: "~", strategy: "merge" }
}

now, let's break this down. For every entry in our ~/.config/yolk/eggs directory, we have a corresponding egg configuration here in the eggs object. This configuration can either just be the path where the eggs files should be deployed, or an object.

If it's an object, it can contain the following fields:

`enabled`

a boolean, describing whether this egg should be deployed or not. This is useful if you only want to deploy an egg on some systems, or depending on some other condition.

`targets`

Either the path where to deploy the egg, or an object with mappings from file inside the egg directory to the target path.

Providing the string "~/.config/foot" is a short for #{ ".": "~/.config/foot"}.

`strategy`

Either "put" or "merge". Defaults to put.

In put mode, yolk will create a symlink for each mapping from egg directory entry to target path. If a directory or file already exists, Yolk will refuse to create the symlink.
In merge mode, yolk will merge the directory structures during deployment. This means, if you want to use a stow-style approach, and have the egg directory mirror your home directory structure, you can use "~" (or #{".": "~"}) as the targets value.

`templates`

A list of files that should be treated as templates. This list can contain shell-style glob patterns, so *.lua will expand to all lua files in the egg directory. Files that are not listed here will not be edited by yolk during yolk sync!

`main_file`

A path, relative to the egg directory, that will be opened when you run yolk edit <eggname>.

Available variables

To generate your configuration depending on your system, there are a couple global variables that you can reference inside the yolk.rhai file. The SYSTEM variable is a table containing data about your local system. If the config is being executed in canonical mode, the SYSTEM table will instead contain a fixed set of values that will be the same across all systems.

To know if you're currently in local or canonical mode, you can check the LOCAL variable.

Tip: To look at the contents of those variables or try out your logic, you can always use the yolk eval command.

$ yolk eval 'print(SYSTEM)'

Conditionals

Yolk allows you to conditionally include parts of your configuration based on the state of your system. It achieves this by commenting or un-commenting blocks of your file.

Conditionals use special template tags that start with the keyword if, which instructs Yolk to treat the following expression as a conditional, rather than a regular template tag function.

Multiline conditionals

The most common form of conditional block is using the multiline template tag syntax. Let's type out a simple example:

# {% if SYSTEM.hostname == "epic-desktop" %}
displays = ["DP-1", "DP-2"]
# {% if SYSTEM.hostname == "business-desktop" %}
displays = ["HDMI-1", "HDMI-2"]
# {% else %}
displays = ["eDP-1"]
# {% end %}

Now, this is of course not a valid configuration just yet, as we're setting the displays variable thrice.

However, once you run yolk sync, yolk will evaluate the condition and comment out the blocks that don't apply. For example, on your laptop, this config might be turned into:

# {% if SYSTEM.hostname == "epic-desktop" %}
#<yolk> displays = ["DP-1", "DP-2"]
# {% if SYSTEM.hostname == "business-desktop" %}
#<yolk> displays = ["HDMI-1", "HDMI-2"]
# {% else %}
displays = ["eDP-1"]
# {% end %}

Note thta yolk added a special <yolk> prefix to the comments. Yolk conditionals will only ever add or remove comments with this prefix, which means that you can still have regular comments in those conditional blocks.

Inline and Next-line conditionals

A more simplified version of this is also supported in inline and next-line tags:

enable_variable_refreshrate // {< if data.is_desktop() >}

// {# if data.enable_xwayland #}
spawn-at-startup "xwayland-satellite"

Custom Template Functions

Given that all of the template functions are just regular Rhai code, you might ask yourself if you can define your own template tag functions. The answer is YES!

How do template tag functions work

Template tag functions are executed in a special context, in which a function called get_yolk_text() is availale. This variable contains the text block that the template tag operates on. A template tag function then returns a string which yolk will replace the old text block with.