Debian Codegraph @

docs/howto/symlink-dotfiles.md

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