| 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 |
``` |