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