| 1 |
# Symlink dotfiles |
| 2 |
|
| 3 |
Dotdrop is able to install dotfiles in four different ways, |
| 4 |
which are controlled by the `link` config attribute of each dotfile: |
| 5 |
|
| 6 |
* `link: nolink`: The dotfile (file or directory) is copied to its destination |
| 7 |
* `link: absolute`: The dotfile (file or directory) is linked to its destination using an absolute symlink |
| 8 |
* `link: relative`: The dotfile (file or directory) is linked to its destination using a relative symlink |
| 9 |
* `link: link_children`: The direct children of the dotfile (directory only) are symlinked to their destination. For every direct child of `src`, symlink `dst/<childrenX>` to `src/<childrenX>` (See [Link children](#link-children)) |
| 10 |
|
| 11 |
Note that if the dotfile uses template directives, it will first be installed to your |
| 12 |
`workdir` (defaults to `~/.config/dotdrop`) and then symlinked |
| 13 |
(see [Templating symlinked dotfiles](#templating-symlinked-dotfiles)). |
| 14 |
|
| 15 |
Although the config entries `link_on_import` and `link_dotfile_default` can be set to the value `link_children`, |
| 16 |
it is not recommended, since operations on a dotfile that is not a directory with the option `link_children` |
| 17 |
will fail. |
| 18 |
|
| 19 |
## Symlink a dotfile |
| 20 |
|
| 21 |
Below is an ad-hoc way to symlink a dotfile when [link_dotfile_default](https://dotdrop.readthedocs.io/en/latest/config/config-config/) |
| 22 |
and [link_on_import](https://dotdrop.readthedocs.io/en/latest/config/config-config/) use their default values. |
| 23 |
|
| 24 |
Import the file: |
| 25 |
```bash |
| 26 |
$ dotdrop import ~/.bashrc |
| 27 |
-> "/home/user/.bashrc" imported |
| 28 |
``` |
| 29 |
|
| 30 |
Edit the `config.yaml` and set the `link` value to `absolute`: |
| 31 |
```yaml |
| 32 |
dotfiles: |
| 33 |
f_bashrc: |
| 34 |
src: bashrc |
| 35 |
dst: ~/.bashrc |
| 36 |
link: absolute |
| 37 |
``` |
| 38 |
|
| 39 |
Install the dotfile, which will remove your `~/.bashrc` and replace it with a link to the file stored in dotdrop: |
| 40 |
```bash |
| 41 |
$ dotdrop install |
| 42 |
Remove "/home/user/.bashrc" for link creation? [y/N] ? y |
| 43 |
-> linked /home/user/.bashrc to /home/user/dotdrop/dotfiles/bashrc |
| 44 |
|
| 45 |
1 dotfile(s) installed. |
| 46 |
``` |
| 47 |
|
| 48 |
The dotfile then points to the file in dotdrop: |
| 49 |
```bash |
| 50 |
$ readlink ~/.bashrc |
| 51 |
/home/user/dotdrop/dotfiles/bashrc |
| 52 |
``` |
| 53 |
|
| 54 |
## Link children |
| 55 |
|
| 56 |
The `link_children` option can be very useful for dotfiles when you don't want the entire |
| 57 |
directory to be symlinked but still want to keep a clean config file (with a |
| 58 |
limited number of entries). Note that `link_children` can only be applied to directories. |
| 59 |
|
| 60 |
*Make sure to do a backup of your dotfiles with something like `cp -r <my-important-dotfile>{,.bak}`.* |
| 61 |
|
| 62 |
A good example of its use is when managing `~/.vim` with dotdrop. |
| 63 |
First let's see what it looks like when using `link: absolute`: |
| 64 |
```yaml |
| 65 |
config: |
| 66 |
dotpath: dotfiles |
| 67 |
dotfiles: |
| 68 |
vim: |
| 69 |
dst: ~/.vim |
| 70 |
src: vim |
| 71 |
link: absolute |
| 72 |
``` |
| 73 |
|
| 74 |
The top directory `~/.vim` is symlinked to the `<dotpath>/vim` location: |
| 75 |
```bash |
| 76 |
$ readlink ~/.vim |
| 77 |
~/.dotfiles/vim/ |
| 78 |
$ ls ~/.dotfiles/vim/ |
| 79 |
after autoload plugged plugin snippets spell swap vimrc |
| 80 |
``` |
| 81 |
|
| 82 |
As a result, all files under `~/.vim` will be managed by |
| 83 |
dotdrop (including unwanted directories like `spell`, `swap`, etc.). |
| 84 |
|
| 85 |
Now with `link_children` dotdrop allows to only symlink |
| 86 |
direct children of the dotfile directory. Let's say only `after`, `plugin`, `snippets`, and `vimrc` |
| 87 |
need to be managed in dotdrop. `~/.vim` is imported in dotdrop and cleaned of all unwanted |
| 88 |
files/directories, and then the `link` entry is set to `link_children` in the config file: |
| 89 |
```yaml |
| 90 |
config: |
| 91 |
dotpath: dotfiles |
| 92 |
dotfiles: |
| 93 |
vim: |
| 94 |
dst: ~/.vim/ |
| 95 |
src: vim |
| 96 |
link: link_children |
| 97 |
``` |
| 98 |
|
| 99 |
Now all children of the `vim` dotfile's directory in the *dotpath* will be symlinked under `~/.vim/` |
| 100 |
without affecting the rest of the local files, keeping the config file clean |
| 101 |
and all unwanted files only on the local system. |
| 102 |
```bash |
| 103 |
$ readlink -f ~/.vim |
| 104 |
~/.vim |
| 105 |
$ tree -L 1 ~/.vim |
| 106 |
~/.vim |
| 107 |
├── after -> ~/.dotfiles/vim/after |
| 108 |
├── autoload |
| 109 |
├── plugged |
| 110 |
├── plugin -> ~/.dotfiles/vim/plugin |
| 111 |
├── snippets -> ~/.dotfiles/vim/snippets |
| 112 |
├── spell |
| 113 |
├── swap |
| 114 |
└── vimrc -> ~/.dotfiles/vim/vimrc |
| 115 |
``` |
| 116 |
|
| 117 |
## Templating symlinked dotfiles |
| 118 |
|
| 119 |
Dotfiles not using any templating directives are directly linked |
| 120 |
to dotdrop's `dotpath` directory (see [the config file doc](../config/config-file.md)). |
| 121 |
|
| 122 |
When using templating directives, however, the dotfiles are first installed into |
| 123 |
`workdir` (defaults to *~/.config/dotdrop*; see [the doc](../config/config-config.md)) |
| 124 |
and then symlinked there. |
| 125 |
This applies to both dotfiles with `link: absolute|relative` and `link: link_children`. |
| 126 |
|
| 127 |
For example: |
| 128 |
```bash |
| 129 |
# with template |
| 130 |
/home/user/.xyz -> /home/user/.config/dotdrop/.xyz |
| 131 |
|
| 132 |
# without template |
| 133 |
/home/user/.xyz -> /home/user/dotfiles/xyz |
| 134 |
``` |