Managing your dotfiles

For quite some time now, I have been versioning my dotfiles in a remote repository on GitHub so that I have them available on each of my devices. In order to roll them out to my clients, I wrote a shell script at the beginning that creates symlinks for the respective files. This worked well in the beginning, but it was not an ideal solution for me as the shell script had to be adapted for each new file in my dotfiles repository. So I looked around for a more official solution and came across GNU stow.

The project is being described as the following on the official website:

GNU Stow is a symlink farm manager which takes distinct packages of software and/or data located in separate directories on the filesystem, and makes them appear to be installed in the same place. For example, /usr/local/bin could contain symlinks to files within /usr/local/stow/emacs/bin, /usr/local/stow/perl/bin etc., and likewise recursively for any other subdirectories such as .../share, .../man, and so on.

How to use stow

The first step is to install the tool via your preferred package manager. See https://github.com/aspiers/stow/blob/master/INSTALL.md for instructions. With brew you can use:

brew install stow

In order to work with stow it is important to layout the files in your directory as if they were in your $HOME folder. For a better understanding I will show you my dotfiles directory with various config files for my environment.

tree -a  ~/dotfiles/ -I .git

/Users/xFuture/dotfiles/
├── .config
│   ├── starship.toml
│   └── zellij
│       └── config.kdl
├── .gitconfig
├── .gitignore_global
├── .prettierignore_global
├── .ssh
│   ├── config
│   └── config.d
│       ├── ssh_config_private
│       └── ssh_config_projects
├── .stow-local-ignore
├── .tmux.conf
├── .vimrc
├── .zshrc
└── README.md

By default, stow will ignore the .git directory and some other folders for the creation of symlinks. If you need additional files or directories to be ignored, you can create a .stow-local-ignore file.

Once you have created a similar folder structure it is important to move or delete the original files because otherwise stow will fail with an error.

So for example:

mv ~/.zshrc ~/.zshrc.bak

After you have successfully moved your original files, it is time to run stow. All you have to do is go to your newly created dotfiles directory and run stow .

cd ~/dotfiles

stow .

You can now check whether everything has worked as desired. To do this, you can check the symlink once.

ls -la ~/.zshrc

/Users/xFuture/.zshrc -> dotfiles/.zshrc

Note: GNU stow will also warn you if the executed command will cause any conflicts.

Sources

GNU stow - https://www.gnu.org/software/stow/

GNU stow documentation - https://www.gnu.org/software/stow/manual/html_node/index.html

GNU stow repository (mirror) - https://github.com/aspiers/stow