| 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). |