Transformations entry¶
For examples of transformation uses, see:
Notes:
- Any transformation with a key starting with an underscore (
_
) won't be shown in output. This can be useful when working with sensitive data containing passwords, for example. - Make sure to quote your transformations to avoid bad surprises
- Transformations are executed using the default shell (
$SHELL
) - To use shell variables in your transformations you need to escape the curly brackets (
${HOME}
becomes${{HOME}}
)
There are two types of transformations available:
-
Read transformations: used to transform dotfiles before they are installed (config key
trans_read
)- Used for commands
install
andcompare
- They have two mandatory arguments:
- {0} will be replaced with the dotfile to process
- {1} will be replaced with a temporary file to store the result of the transformation
- This Happens before the dotfile is templated (see templating)
- Used for commands
-
Write transformations: used to transform files before updating a dotfile (config key
trans_write
)- Used for command
update
andimport
- They have two mandatory arguments:
- {0} will be replaced with the file path to update the dotfile with
- {1} will be replaced with a temporary file to store the result of the transformation
- Used for command
A typical use-case for transformations is when dotfiles need to be stored encrypted or compressed. For more, see the howto.
Note that transformations cannot be used if the dotfile is to be linked (when link: absolute|relative|link_children
).
Transformations also support additional positional arguments that must start from 2 (since {0}
and {1}
are added automatically). The transformations themselves as well as their arguments can also be templated.
For example:
trans_read:
targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1}
dotfiles:
f_abc:
dst: /tmp/abc
src: abc
trans_read: targ "{{@@ profile @@}}" lastarg
profiles:
p1:
dotfiles:
- f_abc
will result in abc; f_abc; p1; lastarg
.
trans_read entry¶
The trans_read entry (optional) contains a transformations mapping (See transformations).
trans_read:
<trans-key>: <command-to-execute>
trans_write entry¶
The trans_write entry (optional) contains a write transformations mapping (See transformations).
trans_write:
<trans-key>: <command-to-execute>
Dynamic transformations¶
As for dynamic actions, transformations support the use of variables (variables and dynvariables and template variables).
A very dumb example:
trans_read:
r_echo_abs_src: echo "{0}: {{@@ _dotfile_abs_src @@}}" > {1}
r_echo_var: echo "{0}: {{@@ r_var @@}}" > {1}
trans_write:
w_echo_key: echo "{0}: {{@@ _dotfile_key @@}}" > {1}
w_echo_var: echo "{0}: {{@@ w_var @@}}" > {1}
variables:
r_var: readvar
w_var: writevar
dotfiles:
f_abc:
dst: ${tmpd}/abc
src: abc
trans_read: r_echo_abs_src
trans_write: w_echo_key
f_def:
dst: ${tmpd}/def
src: def
trans_read: r_echo_var
trans_write: w_echo_var