Manage dotfiles with GNU Stow

In this post, I will try to guide in organise your dotfiles in the cloud and manage them using GNU Stow.

What are dotfiles?

For a casual user, the term dotfiles may sound strange and confusing but it is nothing but application(app) configuration files in developer talk. The apps generally refer to certain files to configure itself.

People usually store these files in a remote location such as a Github repository and retrieve them when needed.

Dotfiles allow personalisation. They can be restored in a new machine saving time. Preparing and organising the dotfiles with some initial effort, help developers save a lot of time later.

A few examples of dotfiles are .bashrc, .vimrc, .gitignore.

Important

Pay attention to personal information inside these files. Never store secure keys, passwords in public domains.

Things to know

• Which app’s config files need to stored.
• Where do those config files are located.

Common config files that need storing

• .bashrc or .zshrc
• .vimrc or init.vim(in the case of neovim)
• .gitignore_global and .gitconfig
• Terminal emulator config files
• IDE of choice config files
• Anyother config you want to save

In fact, if there is an app that you have configured heavily and frequently use, its config files must be stored. In the case the said app doesn’t allow exporting of configurations, it is highly recommended to move onto one that allows it.

Where are most required dotfiles located?

Most files are present in $HOME or $XDG_CONFIG_HOME directories. $XDG_CONFIG_HOME defines the base directory relative to which user-specific configuration files should be stored. If $XDG_CONFIG_HOME is either not set or empty, a default equal to $HOME/.config should be used.

GNU Stow

Some prominent results when googled for storing dotfiles are this Atlassian tutorial and using yadm. However, I found those harder to get started.

GNU Stow on the other hand is an easy-to-use symlink farm manager. As described in their website, it 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.

This strategy works brilliantly for dotfiles. Borrowing explanation from Brandon Invergo’s article:

The procedure is simple. I created the ${HOME}/dotfiles directory and then inside it I made subdirectories for all the programs whose configurations I wanted to manage. Inside each of those directories, I moved in all the appropriate files, maintaining the directory structure of my home directory. So, if a file normally resides at the top level of your home directory, it would go into the top level of the program’s subdirectory. If a file normally goes in the default ${XDG_CONFIG_HOME}/${PKGNAME} location (${HOME}/.config/${PKGNAME}), then it would instead go in ${HOME}/dotfiles/${PKGNAME}/.config/${PKGNAME} and so on.

Install Stow

Terminal

sudo apt stow

brew install stow

1

Ubuntu

2

Homebrew Mac

Placing the files

Now, it might look complex at first. Let me explain with some examples. - .bashrc or .zshrc are present/needed in $HOME directory, so inside $HOME/dotfiles create a subdirectory with bashrc or zshrc and place the original .bashrc or .zshrc file appropriately inside their folder. GNU Stow understands that the dotfile, when symlinked, will create a symlink-copy in the $HOME directory. For future modifications, file in either locations can be edited. But for simplicity, use $HOME/dotfiles directory. - A complicated example would be a config file located deep inside subfolders: nvim’s or neovim’s init.vim or init.lua file. It is present in $HOME/.config/nvim/init.vim. For Stow to understand, it must be placed like this – $HOME/dotfiles/nvim/.config/nvim/init.vim

For further reading, I recommend brilliantly written Jake Weisler’s post on GNU Stow.

Useful Stow commands

If correctly installed, then running the command stow --help should list options to use Stow. Most used commands are

Terminal

stow <packagename>
stow -n <packagename>
stow -D <packagename>
stow -R <packagename>

1

activates symlink

2

trial runs or simulates symlink generation. Effective for checking for errors

3

delete stowed package

4

restows package

Activating Stow

So if we have created three subdirectories inside dotfiles say zsh, git, nvim, then

Terminal

stow bash git nvim

will activate their symlinks.

If returned to $HOME and $XDG_CONFIG_HOME and verified, then we will see,

Terminal

.gitconfig -> .dotfiles/git/.gitconfig
.zshrc -> .dotfiles/zsh/.zshrc
nvim -> ../.dotfiles/nvim/.config/nvim

The most awesome thing in all this is, the directory structure needs to be created only once. For future requirement, one simply clones the dotfiles directory and activates symlinks.

Storing files in Git

The dotfiles directory now becomes important to store in a remote location for safe keeping. Usually a git repository is the preferred method. For instructions on how to use git, look up various tutorials on Git in the internet.

In summary, I have written a short, albeit technical write up on GNU Stow, and its uses for storing dotfiles. Feel free to ask questions in the comments or via various means linked in the blog.