Debian Codegraph @

docs/config/config-transformations.md

raw
1 # Transformations entry
2
3 For examples of transformation uses, see:
4
5 * [Handle compressed directories](../howto/store-compressed-directories.md)
6 * [Handle secrets](../howto/sensitive-dotfiles.md)
7
8 **Notes**:
9
10 * 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.
11 * Make sure to quote your transformations to avoid bad surprises
12 * Transformations are executed using the default shell (`$SHELL`)
13 * To use shell variables in your transformations you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
14
15 There are two types of transformations available:
16
17 * **Install transformations**: used to transform dotfiles before they are installed ([config](config-config.md) key `trans_install`)
18 * Used for commands `install` and `compare`
19 * They have two mandatory arguments:
20 * **{0}** will be replaced with the dotfile to process
21 * **{1}** will be replaced with a temporary file to store the result of the transformation
22 * This Happens **before** the dotfile is templated (see [templating](../template/templating.md))
23
24 * **Update/Import transformations**: used to transform files before updating/importing a dotfile ([config](config-config.md) key `trans_update`)
25 * Used for command `update` and `import`
26 * They have two mandatory arguments:
27 * **{0}** will be replaced with the file path to update the dotfile with
28 * **{1}** will be replaced with a temporary file to store the result of the transformation
29
30 A typical use-case for transformations is when dotfiles need to be
31 stored encrypted or compressed. For more, see [the howto](../howto/howto.md).
32
33 Note that transformations cannot be used if the dotfile is to be linked (when `link: absolute|relative|link_children`).
34
35 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.
36
37 For example:
38 ```yaml
39 trans_install:
40 targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1}
41 dotfiles:
42 f_abc:
43 dst: /tmp/abc
44 src: abc
45 trans_install: targ "{{@@ profile @@}}" lastarg
46 profiles:
47 p1:
48 dotfiles:
49 - f_abc
50 ```
51
52 will result in `abc; f_abc; p1; lastarg`.
53
54 ## trans_install entry
55
56 The **trans_install** entry (optional) contains a transformations mapping (See [transformations](config-transformations.md)).
57
58 ```yaml
59 trans_install:
60 <trans-key>: <command-to-execute>
61 ```
62
63 ## trans_update entry
64
65 The **trans_update** entry (optional) contains a write transformations mapping (See [transformations](config-transformations.md)).
66
67 ```yaml
68 trans_update:
69 <trans-key>: <command-to-execute>
70 ```
71
72 ## Dynamic transformations
73
74 As for [dynamic actions](config-actions.md#dynamic-actions), transformations support
75 the use of variables ([variables and dynvariables](config-file.md#variables)
76 and [template variables](../template/template-variables.md#template-variables)).
77
78 A very dumb example:
79 ```yaml
80 trans_install:
81 r_echo_abs_src: echo "{0}: {{@@ _dotfile_abs_src @@}}" > {1}
82 r_echo_var: echo "{0}: {{@@ r_var @@}}" > {1}
83 trans_update:
84 w_echo_key: echo "{0}: {{@@ _dotfile_key @@}}" > {1}
85 w_echo_var: echo "{0}: {{@@ w_var @@}}" > {1}
86 variables:
87 r_var: readvar
88 w_var: writevar
89 dotfiles:
90 f_abc:
91 dst: ${tmpd}/abc
92 src: abc
93 trans_install: r_echo_abs_src
94 trans_update: w_echo_key
95 f_def:
96 dst: ${tmpd}/def
97 src: def
98 trans_install: r_echo_var
99 trans_update: w_echo_var
100 ```