How to manage dotfiles with GNU Stow
Tags: dotfiles, gnustow
Published: 2019-07-05 14:44:13

---
title: How to manage dotfiles with GNU Stow
published: true
tags: dotfiles, gnu stow
canonical_url: http://www.theguild.nl/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](https://github.com/search?q=dotfile+manager) 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](https://www.gnu.org/software/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](https://brew.sh/):

    $ 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](https://github.com/thnukid/dotfiles).