Debian Codegraph @

docs/config/config-file.md

raw
1 # Config file
2
3 ## Location
4
5 The default config file used by dotdrop is `config.yaml`.
6 A clean base config can be generated using `dotdrop gencfg`.
7
8 Unless specified otherwise, dotdrop will look in the following places for its config file
9 and use the first one found:
10
11 * Current/working directory or the directory where [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) is located if used
12 * `${XDG_CONFIG_HOME}/dotdrop/`
13 * `~/.config/dotdrop/`
14 * `/etc/xdg/dotdrop/`
15 * `/etc/dotdrop/`
16
17 You can force dotdrop to use a different file either by using the `-c`/`--cfg` CLI switch
18 or by defining the `DOTDROP_CONFIG` environment variable.
19
20 ## Variables
21
22 Multiple variables can be used within the config file to
23 parametrize the following elements of the config:
24
25 * Dotfile `src` and `dst` paths (See [Dynamic dotfile paths](config-dotfiles.md#dynamic-dotfile-paths))
26 * External paths
27 * `import_variables`
28 * `import_actions`
29 * `import_configs`
30 * Profiles' `import`
31 * Profiles' `include`
32 * `actions`
33 * `transformations`
34
35 Note that variables used in `actions` and `transformations`
36 are resolved when the action/transformation is executed
37 (See [Dynamic actions](config-actions.md#dynamic-actions),
38 [Dynamic transformations](config-transformations.md#dynamic-transformations) and [Templating](../template/templating.md)).
39
40 The following variables are available in the config files:
41
42 * [Variables defined in the config](config-variables.md)
43 * [Interpreted variables defined in the config](config-dynvars.md)
44 * [User variables defined in the config](config-variables.md)
45 * [Profile variables defined in the config](config-profiles.md#profile-variables-entry)
46 * Environment variables: `{{@@ env['MY_VAR'] @@}}`
47 * The [enriched variables](../template/template-variables.md#enriched-variables)
48 * Dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](../template/templating.md#dotdrop-header))
49
50 as well as all [template methods](../template/template-methods.md) and [template filters](../template/template-filters.md).
51
52 Note that all variables available in the config file will
53 then be available during [templating](../template/templating.md).
54
55 Here are some rules on the use of variables in configs:
56
57 * [dynvariables](config-dynvars.md) are executed in their own file.
58 * [dynvariables](config-dynvars.md) and
59 [variables](config-variables.md) are templated before
60 [dynvariables](config-dynvars.md) are executed.
61 * Config files do not have access to variables defined above in the import tree
62 (variables defined in importing config are not seen by the imported config file,
63 where *import* can be any of `import_configs`, `import_variables`, `import_actions`,
64 profile's `import` and profile's `include`)
65 * [dynvariables](config-dynvars.md) take precedence over [variables](config-variables.md).
66 * Profile `(dyn)variables` take precedence over any other `(dyn)variables`.
67 * Profile `(dyn)variables` take precedence over profile's included `(dyn)variables`.
68 * External/imported `(dyn)variables` take precedence over
69 `(dyn)variables` defined inside the main config file.
70 * [uservariables](config-uservars.md) are ignored if
71 any other variable with the same key is defined.
72
73 For more see the [CONTRIBUTING doc](/CONTRIBUTING.md).
74
75 ## Permissions
76
77 Dotdrop allows to control the permissions applied to a dotfile using the
78 config dotfile entry [chmod](config-dotfiles.md).
79 A [chmod](config-dotfiles.md) entry on a directory
80 is applied to the directory only, not recursively.
81
82 For example:
83 ```yaml
84 dotfiles:
85 f_file:
86 src: file
87 dst: ~/file
88 chmod: 644
89 f_dir:
90 src: dir
91 dst: ~/dir
92 chmod: 744
93 f_preserve:
94 src: pfile
95 dst: ~/pfile
96 chmod: preserve
97 ```
98
99 The `chmod` value defines the file permissions in octal notation to apply to the dotfile. If undefined
100 new files will get the system default permissions (see `umask`, `777-<umask>` for directories and
101 `666-<umask>` for files).
102
103 The special keyword `preserve` allows to ensure that if the dotfiles already exists
104 on the filesystem, its permission is not altered during `install` and the `chmod` config value won't
105 be changed during `update`.
106
107 On `import`, the following rules are applied:
108
109 * If the `-m`/`--preserve-mode` switch is provided or the config option
110 `chmod_on_import` is true, the imported file's permissions are
111 stored in a `chmod` entry
112 * If the imported file's permissions differ from the umask, then the permissions are automatically
113 stored in the `chmod` entry.
114 * Otherwise, no `chmod` entry is added
115
116 On `install`, the following rules are applied:
117
118 * If `chmod` is specified in the dotfile, it will be applied to the installed dotfile.
119 * Otherwise, the permissions of the dotfile in the `dotpath` are applied.
120 * If the global setting `force_chmod` is set to true, dotdrop will not ask
121 for confirmation to apply permissions.
122 * If `chmod` is `preserve` and the destination exists with a different permission set
123 than system default, then it is not altered
124
125 On `update`, the following rule is applied:
126
127 * If the permissions of the file in the filesystem differ from the dotfile in the `dotpath`,
128 then the dotfile entry `chmod` is added/updated accordingly (unless `chmod` value is `preserve`)
129
130 ## Symlinking dotfiles
131
132 see the [symlink dotfiles documentation](../howto/symlink-dotfiles.md).
133
134 ## Template config entries
135
136 Some entries in the config can be templated (See [templating](../template/templating.md)):
137
138 Entry | Related doc
139 -------- | -------------
140 dotpath | [config entries](config-config.md#config-block)
141 dotfile src | [dynamic dotfile paths](config-dotfiles.md#dynamic-dotfile-paths)
142 dotfile dst | [dynamic dotfile paths](config-dotfiles.md#dynamic-dotfile-paths)
143 dotfile link | [dynamic dotfile link value](config-dotfiles.md#dynamic-dotfile-link-value)
144 variables | [variables](config-variables.md)
145 dynvariables | [dynvariables](config-dynvars.md)
146 actions | [dynamic actions](config-dynvars.md)
147 profile include | [Profile include](config-profiles.md#profile-include-entry)
148 profile import | [Profile import](config-profiles.md#profile-import-entry)
149 import_variables | [import_variables](config-config.md#import_variables-entry)
150 import_actions | [import_actions](config-config.md#import_actions-entry)
151 import_configs | [import_configs](config-config.md#import_configs-entry)
152
153 ## All dotfiles for a profile
154
155 To use all defined dotfiles in a profile, simply use
156 the keyword `ALL`.
157
158 For example:
159 ```yaml
160 dotfiles:
161 f_xinitrc:
162 dst: ~/.xinitrc
163 src: xinitrc
164 f_vimrc:
165 dst: ~/.vimrc
166 src: vimrc
167 profiles:
168 host1:
169 dotfiles:
170 - ALL
171 host2:
172 dotfiles:
173 - f_vimrc
174 ```
175
176 ## Ignore patterns
177
178 It is possible to ignore specific patterns when using dotdrop.
179
180 * For [install](../usage.md#install-dotfiles):
181 * Using config block [instignore](config-config.md)
182 * Using dotfiles block [instignore](config-dotfiles.md)
183 * For [import](../usage.md#import-dotfiles):
184 * Using config block [impignore](config-config.md)
185 * For [compare](../usage.md#compare-dotfiles):
186 * Using config block [cmpignore](config-config.md)
187 * Using dotfiles block [cmpignore](config-dotfiles.md)
188 * Using the command line switch `-i`/`--ignore`
189 * For [update](../usage.md#update-dotfiles):
190 * Using config block [upignore](config-config.md)
191 * Using dotfiles block [upignore](config-dotfiles.md)
192 * Using the command line switch `-i`/`--ignore`
193
194 The ignore pattern must follow Unix shell-style wildcards, like for example `*/path/to/file` for files and
195 `*/path/to/directory/*` for directories.
196 Make sure to quote these when using wildcards in the config file.
197
198 ```yaml
199 config:
200 cmpignore:
201 - '*/README.md'
202 upignore:
203 - '*/README.md'
204 instignore:
205 - '*/README.md'
206 impignore:
207 - '*/README.md'
208 ...
209 dotfiles:
210 d_vim
211 dst: ~/.vim
212 src: vim
213 upignore:
214 - '*/undo-dir/*'
215 - '*/plugged/*'
216 instignore:
217 - '*/internal/*'
218 cmpignore:
219 - '*/ignore-me'
220 ...
221 ```
222
223 Patterns used for a specific dotfile can be specified relative to the dotfile destination (`dst`).
224
225 Similar to a `.gitignore` file, you can prefix ignore patterns with an exclamation point (`!`).
226 This so-called "negative ignore pattern" will cause any files that match that pattern to __not__ be ignored,
227 provided they *would have* been ignored by an earlier ignore pattern (dotdrop will warn if that is not the
228 case). This feature allows to, for example, ignore all files within a certain directory, except for a
229 particular one (See examples below).
230
231 For example to ignore everything but the `colors` directory under `~/.vim`
232 ```yaml
233 dotfiles:
234 d_vim
235 dst: ~/.vim
236 src: vim
237 cmpignore:
238 - '*'
239 - '!*/colors/*'
240 ```
241
242 To completely ignore comparison of a specific dotfile:
243 ```yaml
244 dotfiles:
245 d_vim
246 dst: ~/.vim
247 src: vim
248 cmpignore:
249 - '*'
250 ```
251
252 To ignore a specific directory when updating:
253 ```yaml
254 dotfiles:
255 d_colorpicker:
256 src: config/some_directory
257 dst: ~/.config/some_directory
258 upignore:
259 - '*/sub_directory_to_ignore/*'
260 ```
261
262 To ignore a specific file `testfile` and directory `testdir` when importing:
263 ```yaml
264 config:
265 impignore:
266 - "*/testfile"
267 - "testdir"
268 ```
269
270 To ignore all files within a certain directory relative to `dst`, except one called `custom_plugin.zsh`:
271 ```yaml
272 dotfiles:
273 d_zsh:
274 src: zsh
275 dst: ~/.config/zsh
276 upignore:
277 - "*/plugins/*"
278 - "!plugins/custom_plugin.zsh"
279 ```
280
281 To ignore everything except a single file named `file`:
282 ```yaml
283 dotfiles:
284 d_dir
285 src: dir
286 dst: ~/dir
287 cmpignore:
288 - '!file'
289 - '[a-zA-Z0-9]*'
290 ```
291
292 To ignore specific files on different profiles (same `src` but some files
293 are not installed for specific profile)
294 ```yaml
295 dotfiles:
296 d_testdir_p1:
297 src: testdir
298 dst: ~/.testdir
299 instignore:
300 - '*/ignore-me-1'
301 d_testdir_p2:
302 src: testdir
303 dst: ~/.testdir
304 instignore:
305 - '*/ignore-me-2'
306 profiles:
307 p1:
308 dotfiles:
309 - d_testdir_p1
310 p2:
311 dotfiles:
312 - d_testdir_p2
313 ```
314
315 ## Ignore missing
316
317 Sometimes, it is nice to have [update](../usage.md#update-dotfiles) not copy all the files in the installed directory
318 or [compare](../usage.md#compare-dotfiles) diff them.
319
320 For example,
321 maybe you only want to include a single configuration file in your repository
322 and don't want to include other files the program uses,
323 such as a cached files.
324 Maybe you only want to change one file and don't want the others cluttering your repository.
325 Maybe the program changes these files quite often and creates unnecessary diffs in your dotfiles.
326
327 In these cases, you can use the [ignore-missing](config-config.md) option.
328 This option is available as a flag (`--ignore-missing` or `-z`) to the `update` and `compare` commands,
329 or [as ignore-missing in the config](config-config.md).
330
331 To configure globally, place the following in `config.yaml`:
332 ```yaml
333 config:
334 ignore_missing_in_dotdrop: true
335 ```
336
337 To configure per dotfile:
338 ```yaml
339 dotfiles:
340 f_abc:
341 ignore_missing_in_dotdrop: true
342 ```
343
344 ## toml
345
346 Dotdrop should be able to handle `toml` config file however this
347 feature hasn't been extensively tested.
348 A base [config.toml](/config.toml) is available to get started.
349
350 The script [yaml_to_toml.py](https://github.com/deadc0de6/dotdrop/blob/master/scripts/yaml_to_toml.py) allows to convert a `yaml` dotdrop
351 config file to `toml`.
352
353 For more see issue [#343](https://github.com/deadc0de6/dotdrop/issues/343).