How to manage dotfiles with GNU Stow

Dotfiles are text files that live in your $HOME directory and help to configure your terminal and programs. When you are moving to a new computer, having dotfiles in a git repository makes copying these configurations a breeze.

There are quite a lot dotfile managers written in various languages. Basically these dotfile managers create symlinks to the dotfiles in the home directory.

But do we really need a dotfile "manager" to symlink some files?

Meet GNU Stow 🔨

GNU Stow is a symlink farm manager, that makes packages of software appear in different locations on the filesystem.

We can install the software with brew:

$ brew install stow

Making yourself at home 🏠

Let's create a repository dotfiles and create our first dotfile that will be linked to the home directory.

$ mkdir ~/dotfiles
$ cd ~/dotfiles
$ git init .
$ echo "A simple dotfile configuration." > .mydotfile
$ git add .mydotfile
$ git commit -m "Create dotfiles repository"

Now we have a repository, you can easily transfer. Next we need to symlink mydotfile into the home directory.

$ cd ~
$ ln -s ~/dotfiles/mydotfile .mydotfile
$ ls -la | grep mydotfile
lrwxr-xr-x    1 e  ff      20B 29 May 11:11 .mydotfile -> dotfiles/.mydotfile

Now we have symlinked the dotfile in the repository to our home directory. The symlink, which is a reference to the original file, can be edited and viewed. However when you delete the symlink, the original file remains as is.

We can automate the process of manually symlinking the files with Stow. As an example, let's create the following structure to setup neovim configuration files:

$ tree -a ~/dotfiles
.
└── neovim
        └── .config/nvim
        └── .init.vim
    └── .vimrc

With Stow you can link those files by simply running one command.

$ cd ~/dotfiles
$ stow neovim

When we look in our home directory we see the following.

$ ls -la ~ | grep vimrc

lrwxr-xr-x     1 e  ff    22B May 29 11:12 .vimrc ->  dotfiles/neovim/.vimrc

$ ls -la ~/.config/nvim/

lrwxr-xr-x   1 e  ff    43B May 29 11:36 init.vim -> ../../dotfiles/neovim/.config/nvim/init.vim

Let's reflect on what happened 📝

1. We ran stow with our neovim dotfiles directory.

2. Stow finds the .vimrc and the subdirectory .config/nvim/ with an .init.vim.

3. Stow creates a symbolic link one directory above the current location and also creates the structure in the home directory for ~/.config/nvim/ and symlinks .init.vim

Stow makes an assumption that you want to symlink the files one directory above the directory where you have executed the stow command. Having the git repository in ~/dotfiles makes stow create the correct symlinks for us, in the $HOME directory.

In case you want to remove the symlink, you can type stow -D neovim, which will unlink the files. Stow will warn you in case you are about to overwrite existing directories or files.

I am using the described technique to symlink my own dotfiles.