2 | 
3 |
4 | # Yolk – Painfree Templated Dotfile Management
5 |
6 |
7 | 
8 |
9 |
10 |
11 |
12 | Yolk is a cross platform dotfile management tool with a unique spin on templating,
13 | sitting somewhere in between [GNU Stow](https://www.gnu.org/software/stow/) and [chezmoi](https://www.chezmoi.io/).
14 |
15 | Have a look at our [documentation](https://elkowar.github.io/yolk/book) for more information on how to get started!
16 |
17 | ## The Concept
18 |
19 | Yolk allows you to use simple templates in your configuration files without having to worry about keeping a separate template file and the generated config file in sync.
20 | This is achieved through a design that allows all templates to be included inside comments in your actual configuration file.
21 |
22 | Let's demonstrate:
23 |
24 | ```toml
25 | # Use a different font on one host
26 | # {% if SYSTEM.hostname == "epic-desktop" %}
27 | font="Fira Code"
28 | # {% else %}
29 | #
3 |
4 | # Yolk – Painfree Templated Dotfile Management
5 |
6 |
7 |
8 |
9 |
10 |
4 |
5 | **Remember: Always have a good backup of your files before using any tool that modifies your files. Nothing bad should happen here, but better be careful.**
6 |
7 |
8 |
9 | ## How dotfiles are stored
10 |
11 | Yolk manages your dotfiles by storing them in a separate directory, typically inside `~/.config/yolk`.
12 | This allows you to keep your dotfiles in version control easily, and lets you manage your configuration from one central location.
13 |
14 | Yolk groups dotfiles into so-called ["eggs"](eggs.md), which are packages of configuration,
15 | typically for one single application (although you can group them however you want, or even just have one egg for all your configuration files).
16 |
17 | When an egg is "deployed", Yolk creates symlinks in the target location pointing towards the egg directory.
18 | This way, the configured applications will see the configuration files as they expect to see them.
19 |
20 | To define where a set of configuration files should be deployed to, you declare each of your eggs in your [main yolk configuration file](./yolk_rhai.md).
21 | This allows you, among other things, to define a different target directory per system.
22 |
23 | ## Initial setup
24 |
25 | To get started with Yolk, you'll first need to set up the Yolk file structure.
26 |
27 | ```bash
28 | $ yolk init
29 | ```
30 |
31 | This will create the yolk directory, with a default `yolk.rhai` file, and an `eggs` directory.
32 |
33 | ### Adding your first egg
34 |
35 | let's say we want to manage the configuration for the `alacritty` terminal emulator.
36 | To do this, we first move our alacritty configuration into the `eggs` directory:
37 |
38 | ```bash
39 | $ mv ~/.config/alacritty ~/.config/yolk/eggs/
40 | ```
41 |
42 | And then configure the corresponding [egg deployment](./yolk_rhai.md#basic-structure):
43 |
44 | ```rust,ignore
45 | export let eggs = #{
46 | alacritty: #{
47 | targets: "~/.config/alacritty",
48 | templates: ["alacritty.yml"],
49 | enabled: true,
50 | }
51 | }
52 | ```
53 |
54 | Now we can run `yolk sync`!
55 | This will set up a symlink from the target location `~/.config/alacritty`
56 | back to the alacritty egg directory `~/.config/yolk/eggs/alacritty`.
57 |
58 | ### Committing your dots to git
59 |
60 | Now, we want to make sure our dotfiles are in version control and pushed to our git host of choice.
61 | Every interaction with git should be done through the `yolk git` command.
62 | This ensures that git sees the canonical (stable) representation of your files, and automatically performs them from within the yolk directory.
63 |
64 | ```bash
65 | $ yolk safeguard # you only need to run this once.
66 | $ yolk git add --all
67 | $ yolk git commit -m "Setup alacritty"
68 | ```
69 |
70 | To understand what `yolk safeguard` does, see [safeguarding git](./git_concepts.md#safeguarding-git).
71 |
72 | You can now set up your git remote and use git as usual -- just remember to always use `yolk git`, especially when you're committing your files.
73 |
74 | ### Baby's first template
75 |
76 | Because you too are very indecisive about your terminal colors,
77 | you now decide you want to use yolk to manage your color theme for alacritty, and any other applications that you might add later.
78 | You also decide that you want to use a different color scheme on your desktop and your laptop.
79 |
80 | To achieve this, let's first add a declaration of your color theme in your `~/.config/yolk/yolk.rhai` file:
81 |
82 | ```rust,ignore
83 | // ... snip ...
84 |
85 | const themes = #{
86 | gruvbox: #{
87 | background: "#282828",
88 | foreground: "#ebdbb2",
89 | },
90 | mono: #{
91 | background: "#000000",
92 | foreground: "#ffffff",
93 | },
94 | }
95 |
96 | export const data = #{
97 | colors: if SYSTEM.hostname == "laptop" { themes.gruvbox } else { themes.mono }
98 | }
99 | ```
100 |
101 | Beautiful!
102 | 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.
103 | We set up a field `colors`, which we then set to a different color scheme depending on the hostname of the system.
104 |
105 | **Don't forget to `export` any variables you might want to reference in your template tags!**
106 |
107 | Now, let's set up a template in our alacritty config file:
108 |
109 | ```toml
110 | #...
111 | [colors.primary]
112 | background = "#ff0000" # {< replace_color(data.colors.background) >}
113 | foreground = "#ff0000" # {< replace_color(data.colors.foreground) >}
114 | # ...
115 | ```
116 |
117 | Let's break down what's happening here:
118 | Inside the comments after the color declarations, we're using "inline template tags", as indicated by the `{< ... >}` syntax.
119 | These inline tags transform whatever is before them in the line.
120 | 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.
121 |
122 | **Let's try it**!
123 | Run
124 |
125 | ```bash
126 | $ yolk sync
127 | ```
128 |
129 | You will see that, your `alacritty.toml` has changed, and the colors from your `yolk.rhai` file have been applied, depending on your hostname.
130 |
--------------------------------------------------------------------------------
/docs/src/git_concepts.md:
--------------------------------------------------------------------------------
1 | # Git concepts
2 |
3 | Basic familiarity with git is assumed.
4 |
5 | ## Safeguarding git
6 |
7 | Yolk wraps the git CLI to ensure that git only ever interacts with your dotfiles in their canonical state.
8 | If it didn't do that, you would end up committing the local state of your dotfiles,
9 | which would conflict with their state from another machine -- which is what yolk is trying to solve.
10 |
11 | To ensure that you're not accidentally using the regular git CLI for your dotfiles, it is recommended to "safeguard" your dotfiles' git directory.
12 | To do this, simply run
13 |
14 | ```bash
15 | $ yolk safeguard
16 | ```
17 |
18 | after cloning or initializing your dotfiles.
19 |
20 | This simply renames the `.git` directory to `.yolk_git`, which means the regular git CLI won't see the repository anymore.
21 | 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,
22 | but also works from anywhere in your filesystem!
23 |
24 | ## Cloning your dotfiles
25 |
26 | To clone your dotfiles on a new machine, simply clone the repository to `.config/yolk`, and safeguard your git directory.
27 |
28 | ```bash
29 | $ git clone
2 |
3 | # IO Functions
4 |
5 | A collection of functions that can read the environment and filesystem.
6 | These return standardized values in canonical mode.
7 |
8 | ---
9 |
10 | **namespace**: `io`
11 |
12 | ---
13 |
14 |
15 |
16 |
--------------------------------------------------------------------------------
/docs/src/rhai_docs/template.md:
--------------------------------------------------------------------------------
1 |
17 |
18 | ## command_available
19 |
20 |
30 |
31 |
32 |
33 |
34 |
21 |
22 | ```rust,ignore
23 | command_available(name: &str) -> Result
24 | ```
25 |
26 | Check if a given command is available
27 |
28 |
29 |
35 |
36 | ## env
37 |
38 |
48 |
49 |
50 |
51 |
52 |
39 |
40 | ```rust,ignore
41 | env(name: &str, def: &str) -> Result
42 | ```
43 |
44 | Read an environment variable, or return the given default
45 |
46 |
47 |
53 |
54 | ## path_exists
55 |
56 |
66 |
67 |
68 |
69 |
70 |
57 |
58 | ```rust,ignore
59 | path_exists(p: &str) -> Result
60 | ```
61 |
62 | Check if something exists at a given path
63 |
64 |
65 |
71 |
72 | ## path_is_dir
73 |
74 |
84 |
85 |
86 |
87 |
88 |
75 |
76 | ```rust,ignore
77 | path_is_dir(p: &str) -> Result
78 | ```
79 |
80 | Check if the given path is a directory
81 |
82 |
83 |
89 |
90 | ## path_is_file
91 |
92 |
102 |
103 |
104 |
105 |
106 |
93 |
94 | ```rust,ignore
95 | path_is_file(p: &str) -> Result
96 | ```
97 |
98 | Check if the given path is a file
99 |
100 |
101 |
107 |
108 | ## read_dir
109 |
110 |
120 |
121 |
122 |
123 |
124 |
111 |
112 | ```rust,ignore
113 | read_dir(p: &str) -> Result>
114 | ```
115 |
116 | Read the children of a given dir
117 |
118 |
119 |
125 |
126 | ## read_file
127 |
128 |
138 |
139 |
140 |
141 |
142 |
129 |
130 | ```rust,ignore
131 | read_file(p: &str) -> Result
132 | ```
133 |
134 | Read the contents of a given file
135 |
136 |
137 |
2 |
3 | # Template tag functions
4 |
5 | Yolk template tags simply execute rhai functions that transform the block of text the tag operates on.
6 |
7 | Quick reminder: Yolk has three different types of tags, that differ only in what text they operate on:
8 |
9 | - Next-line tags (`{# ... #}`): These tags operate on the line following the tag.
10 | - Inline tags (`{< ... >}`): These tags operate on everything before the tag within the same line.
11 | - Block tags (`{% ... %} ... {% end %}`): These tags operate on everything between the tag and the corresponding `{% end %}` tag.
12 |
13 | Inside these tags, you can call any of Yolks template tag functions (Or, in fact, any rhai expression that returns a string).
14 |
15 | ---
16 |
17 | **namespace**: `template`
18 |
19 | ---
20 |
21 |
22 |
23 |
--------------------------------------------------------------------------------
/docs/src/rhai_docs/utils.md:
--------------------------------------------------------------------------------
1 |
24 |
25 | ## replace_between
26 |
27 |
47 |
48 |
49 |
50 |
51 |
28 |
29 | ```rust,ignore
30 | replace_between(left: &str, right: &str, replacement: &str) -> Result
31 | ```
32 |
33 | **shorthand**: `rbet`.
34 |
35 | Replaces the text between two delimiters with the `replacement`.
36 |
37 | #### Example
38 |
39 | ```handlebars
40 | ui_font = (Arial) # {< replace_between(`(`, `)`, data.font.ui) >}
41 | ```
42 |
43 | Note: we don't need to include the quotes in the replacement here.
44 |
45 |
46 |
52 |
53 | ## replace_color
54 |
55 |
73 |
74 |
75 |
76 |
77 |
56 |
57 | ```rust,ignore
58 | replace_color(replacement: &str) -> Result
59 | ```
60 |
61 | **shorthand**: `rcol`.
62 |
63 | Replaces a hex color value with a new hex color.
64 |
65 | #### Example
66 |
67 | ```handlebars
68 | background_color = "#282828" # {< replace_color(data.colors.bg) >}
69 | ```
70 |
71 |
72 |
78 |
79 | ## replace_in
80 |
81 |
101 |
102 |
103 |
104 |
105 |
82 |
83 | ```rust,ignore
84 | replace_in(between: &str, replacement: &str) -> Result
85 | ```
86 |
87 | **shorthand**: `rin`.
88 |
89 | Replaces the text between two delimiters with the `replacement`.
90 |
91 | #### Example
92 |
93 | ```toml
94 | ui_font = "Arial" # {< replace_in(`"`, data.font.ui) >}
95 | ```
96 |
97 | Note: we don't need to include the quotes in the replacement here.
98 |
99 |
100 |
106 |
107 | ## replace_number
108 |
109 |
127 |
128 |
129 |
130 |
131 |
110 |
111 | ```rust,ignore
112 | replace_number(replacement: Dynamic) -> Result
113 | ```
114 |
115 | **shorthand**: `rnum`.
116 |
117 | Replaces a number with another number.
118 |
119 | #### Example
120 |
121 | ```handlebars
122 | cursor_size = 32 # {< replace_number(data.cursor_size) >}
123 | ```
124 |
125 |
126 |
132 |
133 | ## replace_quoted
134 |
135 |
153 |
154 |
155 |
156 |
157 |
136 |
137 | ```rust,ignore
138 | replace_quoted(replacement: &str) -> Result
139 | ```
140 |
141 | **shorthand**: `rq`.
142 |
143 | Replaces a value between quotes with another value
144 |
145 | #### Example
146 |
147 | ```handlebars
148 | ui_font = "Arial" # {< replace_quoted(data.font.ui) >}
149 | ```
150 |
151 |
152 |
158 |
159 | ## replace_re
160 |
161 |
182 |
183 |
184 |
185 |
186 |
162 |
163 | ```rust,ignore
164 | replace_re(regex: &str, replacement: &str) -> Result
165 | ```
166 |
167 | **shorthand**: `rr`.
168 |
169 | Replaces all occurrences of a Regex `pattern` with `replacement` in the text.
170 |
171 | #### Example
172 |
173 | ```handlebars
174 | ui_font = "Arial" # {< replace_re(`".*"`, `"{data.font.ui}"`) >}
175 | ```
176 |
177 | Note that the replacement value needs to contain the quotes, as those are also matched against in the regex pattern.
178 | Otherwise, we would end up with invalid toml.
179 |
180 |
181 |
187 |
188 | ## replace_value
189 |
190 |
208 |
209 |
210 |
211 |
212 |
191 |
192 | ```rust,ignore
193 | replace_value(replacement: &str) -> Result
194 | ```
195 |
196 | **shorthand**: `rv`.
197 |
198 | Replaces a value (without spaces) after a `:` or a `=` with another value
199 |
200 | #### Example
201 |
202 | ```handlebars
203 | ui_font = Arial # {< replace_value(data.font.ui) >}
204 | ```
205 |
206 |
207 |
2 |
3 | # Utility functions
4 |
5 | A collection of utility functions
6 |
7 | ---
8 |
9 | **namespace**: `utils`
10 |
11 | ---
12 |
13 |
14 |
15 |
--------------------------------------------------------------------------------
/docs/src/templates.md:
--------------------------------------------------------------------------------
1 | # Templates in Yolk
2 |
3 | Yolk allows you to use simple templates directly within your config files.
4 | Those templates will be evaluated whenever you run `yolk sync` or interact with git (see [Git concepts](./git_concepts.md)).
5 |
6 | Expressions within these templates are written in the [Rhai](https://rhai.rs) scripting language,
7 | and have access to a couple special variables that allow you to reference your configuration and system state.
8 |
9 | There are two main kinds of templates in Yolk: [conditional templates](./conditional_templates.md) and [template tag functions](#template-tag-functions).
10 |
11 | ## Preparation
12 | To make yolk evaluate your file as a template, you need to explicitly tell yolk about it.
13 | To do this, make sure you include it in the `templates` list of your eggs deployment configuration in your `yolk.rhai`:
14 |
15 | ```rust,ignore
16 | export let eggs = #{
17 | foo: {
18 | targets: "~/.config/foo",
19 | templates: ["foo.toml"],
20 | }
21 | }
22 | ```
23 |
24 |
25 | ## Conditionals
26 |
27 | You can use [Conditional template elements](./conditional_templates.md) to conditionally include or exclude parts of your configuration.
28 | Let's take a look at a simple example:
29 |
30 | ```toml
31 | # {% if SYSTEM.hostname == "epic-desktop" %}
32 | displays = ["DP-1", "DP-2"]
33 | # {% else %}
34 | displays = ["eDP-1"]
35 | # {% end %}
36 | ```
37 |
38 | Once you run `yolk sync`, yolk will evaluate the condition and comment out the block that doesn't apply.
39 | For example, on your laptop, this config would be turned into:
40 | ```toml
41 | # {% if SYSTEM.hostname == "epic-desktop" %}
42 | #
16 |
17 | ## color_hex_to_rgb
18 |
19 |
29 |
30 |
31 |
32 |
33 |
20 |
21 | ```rust,ignore
22 | color_hex_to_rgb(hex_string: &str) -> Result
28 |
34 |
35 | ## color_hex_to_rgb_str
36 |
37 |
47 |
48 |
49 |
50 |
51 |
38 |
39 | ```rust,ignore
40 | color_hex_to_rgb_str(hex_string: &str) -> Result
41 | ```
42 |
43 | Convert a hex color string to an RGB string.
44 |
45 |
46 |
52 |
53 | ## color_hex_to_rgba_str
54 |
55 |
65 |
66 |
67 |
68 |
69 |
56 |
57 | ```rust,ignore
58 | color_hex_to_rgba_str(hex_string: &str) -> Result
59 | ```
60 |
61 | Convert a hex color string to an RGBA string.
62 |
63 |
64 |
70 |
71 | ## color_rgb_to_hex
72 |
73 |
83 |
84 |
85 |
86 |
87 |
74 |
75 | ```rust,ignore
76 | color_rgb_to_hex(rgb_table: Map) -> Result
77 | ```
78 |
79 | Convert an RGB map to a hex color string.
80 |
81 |
82 |
88 |
89 | ## regex_captures
90 |
91 |
101 |
102 |
103 |
104 |
105 |
92 |
93 | ```rust,ignore
94 | regex_captures(pattern: &str, s: &str) -> Result>>
95 | ```
96 |
97 | Match a string against a regex pattern and return the capture groups as a list.
98 |
99 |
100 |
106 |
107 | ## regex_match
108 |
109 |
119 |
120 |
121 |
122 |
123 |
110 |
111 | ```rust,ignore
112 | regex_match(pattern: &str, haystack: &str) -> Result
113 | ```
114 |
115 | Check if a given string matches a given regex pattern.
116 |
117 |
118 |
124 |
125 | ## regex_replace
126 |
127 |
137 |
138 |
139 |
140 |
141 |
128 |
129 | ```rust,ignore
130 | regex_replace(pattern: &str, haystack: &str, replacement: &str) -> Result
131 | ```
132 |
133 | Replace a regex pattern in a string with a replacement.
134 |
135 |
136 | \n\n{}\n\n---\n\n**namespace**: `{}`\n\n---\n\n",
81 | docs.documentation,
82 | docs.namespace.trim_start_matches("global/")
83 | );
84 |
85 | for item in &docs.items {
86 | mine.push_str(&format!("\n\n{}\n\n", render_item_docs(item)))
87 | }
88 | mine.push_str("\n\n
");
89 |
90 | map.insert(docs.name.to_string(), mine);
91 |
92 | map
93 | }
94 |
95 | fn render_item_docs(item: &Item) -> String {
96 | match item {
97 | Item::Function {
98 | ref root_metadata,
99 | ref metadata,
100 | name,
101 | index: _,
102 | } => {
103 | // dbg!(&metadata);
104 | let docs = root_metadata
105 | .doc_comments
106 | .clone()
107 | .unwrap_or_default()
108 | .join("\n\n")
109 | .lines()
110 | .map(|x| x.trim().trim_start_matches("///").trim().to_string())
111 | .map(|x| {
112 | create_regex("^# ")
113 | .unwrap()
114 | .replace_all(&x, "#### ")
115 | .to_string()
116 | })
117 | // .map(|x| format!("> {x}"))
118 | .collect::
122 |
123 | ## {name}
124 |
125 |
135 | "#,
136 | metadata.iter().map(|x| x.signature.to_string()).collect::
126 |
127 | ```rust,ignore
128 | {}
129 | ```
130 |
131 | {}
132 |
133 |
134 |