Debian Codegraph @

docs/config/config-dotfiles.md

raw
1 # Dotfiles block
2
3 The **dotfiles** entry (mandatory) contains a YAML object with sub-objects for the dotfiles managed by dotdrop. The entries in the sub-objects are as follows:
4
5 Entry | Description
6 -------- | -------------
7 `dst` | Where this dotfile needs to be deployed (dotfiles with empty `dst` are ignored and considered installed, can use `variables`, make sure to quote)
8 `src` | Dotfile path within the `dotpath` (dotfiles with empty `src` are ignored and considered installed, can use `variables`, make sure to quote)
9 `link` | Defines how this dotfile is installed. Possible values: *nolink*, *absolute*, *relative*, *link_children* (See [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) (defaults to value of `link_dotfile_default`)
10 `actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-actions.md))
11 `chmod` | Defines the file permissions in octal notation to apply during installation or the special keyword `preserve` (See [permissions](config-file.md#permissions))
12 `cmpignore` | List of patterns to ignore when comparing (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns))
13 `ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (see [Ignore missing](config-file.md#ignore-missing))
14 `ignoreempty` | If true, an empty template will not be deployed (defaults to the value of `ignoreempty`)
15 `instignore` | List of patterns to ignore when installing (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns))
16 `template` | If false, disable templating for this dotfile (defaults to the value of `template_dotfile_default`)
17 `trans_install` | Transformation key to apply when installing this dotfile (must be defined in the **trans_install** entry below; see [transformations](config-transformations.md))
18 `trans_update` | Transformation key to apply when updating this dotfile (must be defined in the **trans_update** entry below; see [transformations](config-transformations.md))
19 `upignore` | List of patterns to ignore when updating (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns))
20 <s>link_children</s> | Replaced by `link: link_children`
21 <s>trans</s> | Replaced by `trans_install`
22 <s>trans_read</s> | Replaced by `trans_install`
23 <s>trans_write</s> | Replaced by `trans_update`
24
25 ```yaml
26 <dotfile-key-name>:
27 dst: <where-this-file-is-deployed>
28 src: <filename-within-the-dotpath>
29 ## Optional
30 link: (nolink|absolute|relative|link_children)
31 ignoreempty: (true|false)
32 cmpignore:
33 - "<ignore-pattern>"
34 upignore:
35 - "<ignore-pattern>"
36 instignore:
37 - "<ignore-pattern>"
38 actions:
39 - <action-key>
40 template: (true|false)
41 chmod: '<file-permissions>'
42 trans_install: <transformation-key>
43 trans_update: <transformation-key>
44 ```
45
46 ## Dotfile actions
47
48 It is sometimes useful to execute some kind of action
49 when deploying a dotfile.
50
51 Note that a dotfile's actions are only
52 executed when the dotfile is installed (that is, when
53 the version present in dotdrop differs from the one
54 in the filesystem).
55
56 For example, let's consider Vundle, used
57 to manage Vim's plugins. The following action could
58 be set to update and install the plugins when `vimrc` is
59 deployed:
60
61 ```yaml
62 actions:
63 vundle: vim +VundleClean! +VundleInstall +VundleInstall! +qall
64 config:
65 backup: true
66 create: true
67 dotpath: dotfiles
68 dotfiles:
69 f_vimrc:
70 dst: ~/.vimrc
71 src: vimrc
72 actions:
73 - vundle
74 profiles:
75 home:
76 dotfiles:
77 - f_vimrc
78 ```
79
80 Thus, when `f_vimrc` is installed, the command
81 `vim +VundleClean! +VundleInstall +VundleInstall! +qall` will
82 be executed.
83
84 Sometimes, you may even want to execute some action prior to deploying a dotfile.
85 Let's take another example with
86 [vim-plug](https://github.com/junegunn/vim-plug):
87
88 ```yaml
89 actions:
90 pre:
91 vim-plug-install: test -e ~/.vim/autoload/plug.vim || (mkdir -p ~/.vim/autoload; curl
92 -fLo ~/.vim/autoload/plug.vim https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim)
93 vim-plug: vim +PlugInstall +qall
94 config:
95 backup: true
96 create: true
97 dotpath: dotfiles
98 dotfiles:
99 f_vimrc:
100 dst: ~/.vimrc
101 src: vimrc
102 actions:
103 - vim-plug-install
104 - vim-plug
105 profiles:
106 home:
107 dotfiles:
108 - f_vimrc
109 ```
110
111 This way, we make sure [vim-plug](https://github.com/junegunn/vim-plug)
112 is installed prior to deploying the `~/.vimrc` dotfile.
113
114 You can also define `post` actions like this:
115
116 ```yaml
117 actions:
118 post:
119 some-action: echo "Hello, World!" >/tmp/log
120 ```
121
122 Actions can even be parameterized. For example:
123
124 ```yaml
125 actions:
126 echoaction: echo '{0}' > {1}
127 config:
128 backup: true
129 create: true
130 dotpath: dotfiles
131 dotfiles:
132 f_vimrc:
133 dst: ~/.vimrc
134 src: vimrc
135 actions:
136 - echoaction "vim installed" /tmp/mydotdrop.log
137 f_xinitrc:
138 dst: ~/.xinitrc
139 src: xinitrc
140 actions:
141 - echoaction "xinitrc installed" /tmp/myotherlog.log
142 profiles:
143 home:
144 dotfiles:
145 - f_vimrc
146 - f_xinitrc
147 ```
148
149 The above will execute `echo 'vim installed' > /tmp/mydotdrop.log` when
150 vimrc is installed and `echo 'xinitrc installed' > /tmp/myotherlog.log'`
151 when xinitrc is installed.
152
153 ## Dynamic dotfile paths
154
155 Dotfile source (`src`) and destination (`dst`) paths can be dynamically constructed using
156 defined variables ([variables and dynvariables](config-file.md#variables)).
157
158 For example, to have a dotfile deployed on a unique Firefox profile where the
159 profile path is dynamically found using a shell oneliner stored in a dynvariable:
160 ```yaml
161 dynvariables:
162 mozpath: find ~/.mozilla/firefox -name '*.default'
163 dotfiles:
164 f_somefile:
165 dst: "{{@@ mozpath @@}}/somefile"
166 src: firefox/somefile
167 profiles:
168 home:
169 dotfiles:
170 - f_somefile
171 ```
172
173 Or when you need to select the dotfile to deploy depending on
174 the profile used (`ssh_config.perso` for the profile `perso` and
175 `ssh_config.work` for the `work` profile):
176 ```yaml
177 dotfiles:
178 f_ssh_config:
179 src: "{{@@ ssh_config_file @@}}"
180 dst: ~/.ssh/config
181 profiles:
182 perso:
183 dotfiles:
184 - f_ssh_config
185 variables:
186 - ssh_config_file: "ssh_config.perso"
187 work:
188 dotfiles:
189 - f_ssh_config
190 variables:
191 - ssh_config_file: "ssh_config.work"
192 ```
193
194 ## Dynamic dotfile link value
195
196 Dotfile `link` values can be dynamically constructed using
197 defined variables ([variables and dynvariables](config-file.md#variables)).
198
199 For example:
200 ```yaml
201 variables:
202 link_value: "nolink"
203 dotfiles:
204 f_test:
205 src: test
206 dst: ~/.test
207 link: "{{@@ link_value @@}}"
208 profiles:
209 linux:
210 dotfiles:
211 - f_test
212 variables:
213 link_value: "absolute"
214 windows:
215 dotfiles:
216 - f_test
217 ```
218
219 Make sure to quote the link value in the config file.