Debian Codegraph @

docs/usage.md

raw
1 # Usage
2
3 Run `dotdrop --help` to see all available options.
4
5 ## Profile
6
7 The default profile used by dotdrop is the *hostname* of the host you are running dotdrop on.
8
9 It can be changed:
10
11 * Using the command line switch `-p`/`--profile=<profile>`
12 * By defining it in the env variable `DOTDROP_PROFILE`
13
14 ## List profiles
15
16 The `profiles` command lists the profiles defined in the config file.
17 ```bash
18 $ dotdrop profiles
19 ```
20
21 Dotdrop allows to choose which profile to use
22 with the `--profile` switch if you use something
23 other than the default (the hostname).
24
25 The default profile can also be changed by defining the
26 `DOTDROP_PROFILE` environment variable.
27
28 ## Import dotfiles
29
30 The `import` command imports dotfiles to be managed by dotdrop.
31 It copies the dotfile to your `dotpath` and updates the config file with the new entry.
32
33 Dotdrop will ask whether to dereference symlinks on import unless `-f`/`--force` is used.
34
35 For example, to import `~/.xinitrc`:
36 ```bash
37 $ dotdrop import ~/.xinitrc
38 -> "/home/user/.xinitrc" imported
39
40 1 file(s) imported.
41 ```
42
43 You can explicitely provide the key dotdrop should use for the dotfile entry
44 in the config file with the `-K --dkey` cli switch. Note that the provided
45 string will be sanitized for yaml. Also if the key already exists,
46 it will be appended with `_<incremental_number>` to avoid duplicates.
47
48 If the key is not provided, it will be automatically created based on the
49 following [config entries](config/config-config.md):
50
51 * `longkey`
52 * `false` (default): take the shortest unique path
53 * `true` take the full path
54 * `key_prefix`: defines if the key is prefixed with `f<key_separator>` for file and `d<key_separator>` for directory
55 * `key_separator`: defines the separator to use (defaults to `_`)
56
57 For example, `~/.config/awesome/rc.lua` gives:
58
59 * `f_rc.lua` in the short format
60 * `f_config_awesome_rc.lua` in the long format
61
62 Importing `~/.mutt/colors` and then `~/.vim/colors` will result in:
63
64 * `d_colors` and `d_vim_colors` in the short format
65 * `d_mutt_colors` and `d_vim_colors` in the long format
66
67 It is possible to import a dotfile while pretending it was at a different
68 path with the use of `--as` what will effectively modify the `src` path
69 of the generated dotfile entry in the config as well as the location of the file
70 in the *dotpath*.
71 The argument to `--as` is expected to be an absolute path and will be made
72 absolute in case it isn't (specifying `--as test` will result in something like
73 `--as <current-working-directory>/test`). It is however recommended
74 to use [templating](template/templating.md) to avoid duplicates and optimize
75 dotfile management instead of using `--as`.
76 ```bash
77 # imported to <dotpath>/zshrc.test
78 $ dotdrop import ~/.zshrc --as=~/.zshrc.test
79 ```
80 see [issue #220](https://github.com/deadc0de6/dotdrop/issues/220) and [issue #368](https://github.com/deadc0de6/dotdrop/issues/368).
81
82 By importing a path using the profile special keyword `ALL`, a dotfile will be created
83 in the config but won't be associated to any profile.
84
85 To ignore specific patterns during import, see [the ignore patterns](config/config-file.md#ignore-patterns).
86
87 For more options, see the usage with `dotdrop --help`.
88
89 ## Install dotfiles
90
91 The `install` command installs/deploys dotfiles managed by dotdrop from the `dotpath` to their destinations.
92 ```bash
93 $ dotdrop install
94 ```
95
96 A dotfile will be installed only if it differs from the version already present at its destination.
97
98 Some available options:
99
100 * `-t`/`--temp`: Install the dotfile(s) to a temporary directory for review (helping to debug templating issues, for example).
101 Note that actions are not executed in this mode.
102 * `-a`/`--force-actions`: Force the execution of actions even if the dotfiles are not installed (see [Fake dotfile and actions](config/config-actions.md#fake-dotfile-and-actions) as an alternative)
103 * `-f`/`--force`: Do not ask for any confirmation
104 * `-W`/`--workdir-clear`: Clear the `workdir` before installing dotfiles (see [the config entry](config/config-config.md) `clear_workdir`)
105 * `-R`/`remove-existing`: Applies to directory dotfiles only (`nolink`) and will remove files not managed by dotdrop in the destination directory
106
107 To ignore specific patterns during installation, see [the ignore patterns](config/config-file.md#ignore-patterns).
108
109 For more options, see the usage with `dotdrop --help`.
110
111 ## Compare dotfiles
112
113 The `compare` command compares dotfiles at their destinations with the ones stored in your `dotpath`.
114 ```bash
115 $ dotdrop compare
116 ```
117
118 The diffing is done with the UNIX tool `diff` as the backend; one can provide a specific
119 diff command using [the config entry](config/config-config.md) `diff_command`.
120
121 You can specify against which destination file to compare:
122 ```bash
123 $ dotdrop compare -C ~/.vimrc
124 ```
125
126 To ignore specific patterns, see [the ignore patterns](config/config-file.md#ignore-patterns).
127
128 To completely ignore all files not present in `dotpath` see [Ignore missing](config/config-file.md#ignore-missing).
129
130 If you want to get notified on files present in the `workdir` but not tracked
131 by dotdrop see the [compare_workdir](config/config-config.md).
132
133 For more options, see the usage with `dotdrop --help`.
134
135 ## List dotfiles
136
137 The `files` command lists the dotfiles declared for a specific profile.
138 ```bash
139 $ dotdrop files --profile=some-profile
140 f_xinitrc
141 -> dst: /home/user/.xinitrc
142 -> src: /home/user/dotdrop/dotfiles/xinitrc
143 -> link: nolink
144 ```
145
146 By using the `-T`/`--template` switch, only the dotfiles that
147 are using [templating](template/templating.md) are listed.
148
149 It is also possible to list all the files related to each dotfile entry
150 by invoking the `detail` command, for example:
151 ```bash
152 $ dotdrop detail
153 dotfiles details for profile "some-profile":
154 f_xinitrc (dst: "/home/user/.xinitrc", link: nolink)
155 -> /home/user/dotdrop/dotfiles/xinitrc (template:no)
156 ```
157
158 This is especially useful when the dotfile entry is a directory
159 and one wants to have information on the different files it contains
160 (does a specific file uses templating, etc.).
161
162 For more options, see the usage with `dotdrop --help`.
163
164 ## Update dotfiles
165
166 The `update` command updates a dotfile managed by dotdrop by copying the dotfile
167 from the filesystem to the `dotpath`. Only dotfiles that have differences with the stored version are updated.
168 A confirmation is requested from the user before any overwrite/update unless the `-f`/`--force` switch is used.
169
170 Either provide the path of the file containing the new version of the dotfile or
171 provide the dotfile key to update (as found in the config file) along with the `-k`/`--key` switch.
172 When using the `-k`/`--key` switch and no key is provided, all dotfiles for that profile are updated.
173 ```bash
174 ## update by path
175 $ dotdrop update ~/.vimrc
176
177 ## update by key with the --key switch
178 $ dotdrop update --key f_vimrc
179 ```
180
181 If not argument is provided, all dotfiles for the selected profile are updated.
182
183 To ignore specific patterns, see [the dedicated page](config/config-file.md#ignore-patterns).
184
185 To completely ignore all files not present in `dotpath`, see [Ignore missing](config/config-file.md#ignore-missing).
186
187 There are two cases when updating a dotfile:
188
189 * [The dotfile does not use templating](#the-dotfile-does-not-use-templating)
190 * [The dotfile uses templating](#the-dotfile-uses-templating)
191
192 ### The dotfile does not use [templating](template/templating.md)
193
194 The new version of the dotfile is copied to the *dotpath* directory and overwrites
195 the old version. If Git is used to version the dotfiles stored by dotdrop, the Git command
196 `diff` can be used to view the changes.
197
198 ```bash
199 $ dotdrop update ~/.vimrc
200 $ git diff
201 ```
202
203 ### The dotfile uses [templating](template/templating.md)
204
205 The dotfile must be manually updated; three solutions can be used to identify the
206 changes to apply to the template:
207
208 * Use the `compare` command:
209 ```bash
210 ## use compare to identify change(s)
211 $ dotdrop compare --file=~/.vimrc
212 ```
213
214 * Call `update` with the `-P`/`--show-patch` switch, which provides an ad-hoc solution
215 to manually patch the template file using a temporary generated version of the template.
216 (This isn't a bullet-proof solution and might need manual checking.)
217 ```bash
218 ## get an ad-hoc solution to manually patch the template
219 $ dotdrop update --show-patch ~/.vimrc
220 [WARN] /home/user/dotfiles/vimrc uses template, update manually
221 [WARN] try patching with: "diff -u /tmp/dotdrop-sbx6hw0r /home/user/.vimrc | patch /home/user/dotfiles/vimrc"
222 ```
223
224 * Install the dotfiles to a temporary directory (using the `install` command and the
225 `-t` switch) and compare the generated dotfile with the local one:
226 ```bash
227 ## use install to identify change(s)
228 $ dotdrop install -t -t f_vimrc
229 Installed to tmp /tmp/dotdrop-6ajz7565
230 $ diff ~/.vimrc /tmp/dotdrop-6ajz7565/home/user/.vimrc
231 ```
232
233 ## Remove dotfiles
234
235 The command `remove` allows to stop managing a specific dotfile with
236 dotdrop. It will:
237
238 * remove the entry from the config file (under `dotfiles` and `profile`)
239 * delete the file from the `dotpath`
240
241 For more options, see the usage with `dotdrop --help`.
242
243 ## Uninstall dotfiles
244
245 The `uninstall` command removes dotfiles installed by dotdrop
246 ```bash
247 $ dotdrop uninstall
248 ```
249
250 It will remove the installed dotfiles related to the provided key
251 (or all dotfiles if not provided) of the selected profile.
252
253 If a backup exists ([backup entry](config/config-config.md#backup-entry)),
254 the file will be restored.
255
256 For more options, see the usage with `dotdrop --help`.
257
258 ## Generate a default config
259
260 The `gencfg` command will generate a default config in yaml
261 ```bash
262 $ dotdrop gencfg > config.yaml
263 ```
264
265 ## Concurrency
266
267 The command line switch `-w`/`--workers`, if set to a value greater than one, enables the use
268 of multiple concurrent workers to execute an operation. It can be applied to the following
269 commands:
270
271 * `install`
272 * `compare`
273 * `update`
274
275 It should be set to a maximum of the number of cores available (usually returned
276 on linux by the command `nproc`).
277
278 It may speed up the operation but cannot be used interactively (it needs `-f`/`--force` to be set
279 except for `compare`) and cannot be used with `-d`/`--dry`. Also, information printed to stdout/stderr
280 will probably be messed up.
281
282 **WARNING:** This feature hasn't been extensively tested and is to be used at your own risk.
283 If you try it out and find any issues, please [report them](https://github.com/deadc0de6/dotdrop/issues).
284 Also, if you find it useful and have been able to successfully speed up your operation when using
285 `-w`/`--workers`, do please also report it [in an issue](https://github.com/deadc0de6/dotdrop/issues).
286
287 ## Environment variables
288
289 The following environment variables can be used to specify different CLI options and change behaviors.
290 Note that CLI switches take precedence over environment variables
291
292 `DOTDROP_PROFILE`: `-p`/`--profile`
293 ```bash
294 export DOTDROP_PROFILE="my-fancy-profile"
295 ```
296
297 `DOTDROP_CONFIG`: `-c`/`--cfg`
298 ```bash
299 export DOTDROP_CONFIG="/home/user/dotdrop/config.yaml"
300 ```
301
302 `DOTDROP_NOBANNER`: `-b`/`--no-banner`
303 ```bash
304 export DOTDROP_NOBANNER=
305 ```
306
307 `DOTDROP_DEBUG`: `-V`/`--verbose`
308 ```bash
309 export DOTDROP_DEBUG=
310 ```
311
312 `DOTDROP_FORCE_NODEBUG`: disable debug output even if `-V`/`--verbose` is provided or `DOTDROP_DEBUG` is set
313 ```bash
314 export DOTDROP_FORCE_NODEBUG=
315 ```
316
317 `DOTDROP_TMPDIR`: defines a temporary directory for dotdrop to use for its operations instead of using a system generated one
318 ```bash
319 export DOTDROP_TMPDIR="/tmp/dotdrop-tmp"
320 ```
321
322 `DOTDROP_WORKDIR`: overwrite the `workdir` defined in the config
323 ```bash
324 export DOTDROP_WORKDIR="/tmp/dotdrop-workdir"
325 ```
326
327 `DOTDROP_WORKERS`: overwrite the `-w`/`--workers` cli argument
328 ```bash
329 export DOTDROP_WORKERS="10"
330 ```
331
332 `DOTDROP_MIME_TEXT`: comma separated list of mime type to treat as text during templating
333 ```bash
334 export DOTDROP_MIME_TEXT=application/x-wine-extension-ini
335 ```