Debian Codegraph @

docs/config/config-config.md

raw
1 # Config block
2
3 The **config** entry (mandatory) contains global settings.
4
5 Entry | Description | Default
6 -------- | ------------- | ------------
7 `backup` | Create a backup of the existing destination; see [backup entry](config-config.md#backup-entry)) | true
8 `banner` | Display the banner | true
9 `check_version` | Check if a new version of dotdrop is available on github | false
10 `chmod_on_import` | Always add a chmod entry on newly imported dotfiles (see `--preserve-mode`) | false
11 `clear_workdir` | On `install` clear the `workdir` before installing dotfiles (see `--workdir-clear`) | false
12 `compare_workdir` | On `compare` notify on files in `workdir` not tracked by dotdrop | false
13 `cmpignore` | List of patterns to ignore when comparing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | -
14 `create` | Create a directory hierarchy when installing dotfiles if it doesn't exist | true
15 `default_actions` | List of action keys to execute for all installed dotfiles (See [actions](config-actions.md)) | -
16 `diff_command` | The diff command to use for diffing files | `diff -r -u {0} {1}`
17 `dotpath` | Path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location) | `dotfiles`
18 `filter_file` | List of paths to load templating filters from (See [Templating available filters](../template/template-filters.md)) | -
19 `force_chmod` | If true, do not ask confirmation to apply permissions on install | false
20 `func_file` | List of paths to load templating functions from (See [Templating available methods](../template/template-methods.md)) | -
21 `ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (See [Ignore missing](config-file.md#ignore-missing)) | false
22 `ignoreempty` | Do not deploy template if empty | false
23 `impignore` | List of patterns to ignore when importing (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | -
24 `import_actions` | List of paths to load actions from (absolute path or relative to the config file location; see [Import actions from file](config-config.md#import_actions-entry)) | -
25 `import_configs` | List of config file paths to be imported into the current config (absolute paths or relative to the current config file location; see [Import config files](config-config.md#import_configs-entry)) | -
26 `import_variables` | List of paths to load variables from (absolute paths or relative to the config file location; see [Import variables from file](config-config.md#import_variables-entry)) | -
27 `instignore` | List of patterns to ignore when installing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | -
28 `keepdot` | Preserve leading dot when importing hidden file in the `dotpath` | false
29 `key_prefix` | Prefix dotfile key on `import` with `f<key_separator>` for file and `d<key_separator>` for directory | true
30 `key_separator` | Separator to use on dotfile key generation on `import` | `_`
31 `link_dotfile_default` | Set a dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *absolute*, *relative* (See [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) | `nolink`
32 `link_on_import` | Set a dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *absolute*, *relative* [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) | `nolink`
33 `longkey` | Use long keys for dotfiles when importing (See [Import dotfiles](../usage.md#import-dotfiles)) | false
34 `minversion` | (*for internal use, do not modify*) Provides the minimal dotdrop version to use | -
35 `showdiff` | On install, show a diff before asking to overwrite (See `--showdiff`) | false
36 `template_dotfile_default` | Disable templating on all dotfiles when set to false | true
37 `upignore` | List of patterns to ignore when updating, appled to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | -
38 `workdir` | Path to the directory where templates are installed before being symlinked when using `link:absolute|relative|link_children` (absolute path or relative to the config file location) | `~/.config/dotdrop`
39 <s>link_by_default</s> | When importing a dotfile, set `link` to this value by default | false
40
41 ## import_variables entry
42
43 It is possible to load variables/dynvariables from external files by providing their
44 paths in the config entry `import_variables`.
45
46 The paths can be absolute or relative to the config file location.
47
48 `config.yaml`
49 ```yaml
50 config:
51 backup: true
52 create: true
53 dotpath: dotfiles
54 import_variables:
55 - variables.d/myvars.yaml
56 ```
57
58 `variables.d/myvars.yaml`
59 ```yaml
60 variables:
61 var1: "extvar1"
62 dynvariables:
63 dvar1: "echo extdvar1"
64 ```
65
66 Dotdrop will fail if an imported path points to a non-existing file.
67 It is possible to make non-existing paths not fatal by appending `:optional` to the path:
68 ```yaml
69 import_variables:
70 - variables.d/myvars.yaml:optional
71 ```
72
73 ## import_actions entry
74
75 It is possible to load actions from external files by providing their
76 paths in the config entry `import_actions`.
77
78 The paths can be absolute or relative to the config file location.
79
80 `config.yaml`
81 ```yaml
82 config:
83 backup: true
84 create: true
85 dotpath: dotfiles
86 import_actions:
87 - actions.d/myactions.yaml
88 dotfiles:
89 f_abc:
90 dst: ~/.abc
91 src: abc
92 actions:
93 - dateme
94 ```
95
96 `actions.d/myactions.yaml`
97 ```yaml
98 actions:
99 dateme: date > /tmp/timestamp
100 ```
101
102 External/imported variables will take precedence over variables defined
103 inside the main config file.
104
105 Dotdrop will fail if an imported path points to a non-existing file.
106 It is possible to make non-existing paths not fatal by appending `:optional` to the path:
107 ```yaml
108 import_actions:
109 - actions.d/myactions.yaml:optional
110 ```
111
112 ## import_configs entry
113
114 Entire config files can be imported using the `import_configs` entry.
115 This means making the following available from the imported config file in the original config file:
116
117 * dotfiles
118 * profiles
119 * actions
120 * read/write transformations
121 * variables/dynvariables
122
123 Paths to import can be absolute or relative to the importing config file
124 location.
125
126 `config.yaml`
127 ```yaml
128 config:
129 backup: true
130 create: true
131 dotpath: dotfiles
132 import_configs:
133 - other-config.yaml
134 dotfiles:
135 f_abc:
136 dst: ~/.abc
137 src: abc
138 actions:
139 - show
140 profiles:
141 my-host:
142 dotfiles:
143 - f_abc
144 - f_def
145 my-haskell:
146 include:
147 - other-host
148 ```
149
150 `other-config.yaml`
151 ```yaml
152 config:
153 backup: true
154 create: true
155 dotpath: dotfiles-other
156 import_actions:
157 - actions.yaml
158 dotfiles:
159 f_def:
160 dst: ~/.def
161 src: def
162 f_ghci:
163 dst: ~/.ghci
164 src: ghci
165 profiles:
166 other-host:
167 dotfiles:
168 - f_gchi
169 ```
170
171 `actions.yaml`
172 ```yaml
173 actions:
174 post:
175 show: less
176 ```
177
178 In this example, `config.yaml` imports `other-config.yaml`. The dotfile `f_def`
179 used in the profile `my-host` is defined in `other-config.yaml`, and so is the
180 profile `other-host` included from `my-haskell`. The action `show` is defined
181 in `actions.yaml`, which is in turn imported by `other-config.yaml`.
182
183 Dotdrop will fail if an imported path points to a non-existing file.
184 It is possible to make non-existing paths not fatal by appending `:optional` to the path.
185 ```yaml
186 import_configs:
187 - other-config.yaml:optional
188 ```
189
190 In case of a name clash (same name in importing and imported configs),
191 the importing config will take precedence except for the `variables` and `dynvariables`
192 (see [variable](config-file.md#variables) and [CONTRIBUTING doc](/CONTRIBUTING.md)).
193
194 ## default_actions entry
195
196 Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (`pre` or `post`).
197
198 For example, the below action will log each dotfile installation to a file.
199
200 ```yaml
201 actions:
202 post:
203 loginstall: "echo {{@@ _dotfile_abs_src @@}} installed to {{@@ _dotfile_abs_dst @@}} >> {0}"
204 config:
205 backup: true
206 create: true
207 dotpath: dotfiles
208 default_actions:
209 - loginstall "/tmp/dotdrop-installation.log"
210 dotfiles:
211 f_vimrc:
212 dst: ~/.vimrc
213 src: vimrc
214 profiles:
215 hostname:
216 dotfiles:
217 - f_vimrc
218 ```
219
220 ## backup entry
221
222 When set to `true`, existing files that would be replaced
223 by a dotdrop `install`, are backed up with the
224 extension `.dotdropbak` if their content differ.
225
226 Note:
227 * directories will **not** be backed up, only files
228 * when using a different `link` value than `nolink` with directories,
229 the files under the directory will **not** be backed up
230 (See [Symlinking dotfiles](config-file.md#symlinking-dotfiles)),