symlink-dotfiles.md

Symlink dotfiles

Dotdrop is able to install dotfiles in four different ways, which are controlled by the link config attribute of each dotfile:

• link: nolink: The dotfile (file or directory) is copied to its destination
• link: absolute: The dotfile (file or directory) is linked to its destination using an absolute symlink
• link: relative: The dotfile (file or directory) is linked to its destination using a relative symlink
• 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)

Note that if the dotfile uses template directives, it will first be installed to your workdir (defaults to ~/.config/dotdrop) and then symlinked (see Templating symlinked dotfiles).

Although the config entries link_on_import and link_dotfile_default can be set to the value link_children, it is not recommended, since operations on a dotfile that is not a directory with the option link_children will fail.

Symlink a dotfile

Below is an ad-hoc way to symlink a dotfile when link_dotfile_default and link_on_import use their default values.

Import the file:

$ dotdrop import ~/.bashrc
	-> "/home/user/.bashrc" imported

Edit the config.yaml and set the link value to absolute:

dotfiles:
  f_bashrc:
    src: bashrc
    dst: ~/.bashrc
    link: absolute

Install the dotfile, which will remove your ~/.bashrc and replace it with a link to the file stored in dotdrop:

$ dotdrop install
Remove "/home/user/.bashrc" for link creation? [y/N] ? y
	-> linked /home/user/.bashrc to /home/user/dotdrop/dotfiles/bashrc

1 dotfile(s) installed.

The dotfile then points to the file in dotdrop:

$ readlink ~/.bashrc
/home/user/dotdrop/dotfiles/bashrc

Link children

The link_children option can be very useful for dotfiles when you don't want the entire directory to be symlinked but still want to keep a clean config file (with a limited number of entries). Note that link_children can only be applied to directories.

Make sure to do a backup of your dotfiles with something like cp -r <my-important-dotfile>{,.bak}.

A good example of its use is when managing ~/.vim with dotdrop. First let's see what it looks like when using link: absolute:

config:
  dotpath: dotfiles
dotfiles:
  vim:
    dst: ~/.vim
    src: vim
    link: absolute

The top directory ~/.vim is symlinked to the <dotpath>/vim location:

$ readlink ~/.vim
~/.dotfiles/vim/
$ ls ~/.dotfiles/vim/
after  autoload  plugged  plugin  snippets  spell  swap  vimrc

As a result, all files under ~/.vim will be managed by dotdrop (including unwanted directories like spell, swap, etc.).

Now with link_children dotdrop allows to only symlink direct children of the dotfile directory. Let's say only after, plugin, snippets, and vimrc need to be managed in dotdrop. ~/.vim is imported in dotdrop and cleaned of all unwanted files/directories, and then the link entry is set to link_children in the config file:

config:
  dotpath: dotfiles
dotfiles:
  vim:
    dst: ~/.vim/
    src: vim
    link: link_children

Now all children of the vim dotfile's directory in the dotpath will be symlinked under ~/.vim/ without affecting the rest of the local files, keeping the config file clean and all unwanted files only on the local system.

$ readlink -f ~/.vim
~/.vim
$ tree -L 1 ~/.vim
~/.vim
├── after -> ~/.dotfiles/vim/after
├── autoload
├── plugged
├── plugin -> ~/.dotfiles/vim/plugin
├── snippets -> ~/.dotfiles/vim/snippets
├── spell
├── swap
└── vimrc -> ~/.dotfiles/vim/vimrc

Templating symlinked dotfiles

Dotfiles not using any templating directives are directly linked to dotdrop's dotpath directory (see the config file doc).

When using templating directives, however, the dotfiles are first installed into workdir (defaults to ~/.config/dotdrop; see the doc) and then symlinked there. This applies to both dotfiles with link: absolute|relative and link: link_children.

For example:

# with template
/home/user/.xyz -> /home/user/.config/dotdrop/.xyz

# without template
/home/user/.xyz -> /home/user/dotfiles/xyz