Managing dotfiles

If you ever used the command line, you probably have heard of dotfiles. Although the word dotfile could refer to hidden files in general in the *nix world, it is usually used to refer to the configuration files of various command line programs, such as bash and vim. When you start to seriously use the command line, you will find that you need to change configurations for programs. For example, you need to update your PATH inside .bashrc. Managing these dotfiles is very important because it allows you to easily setup a new environment in case you need to reinstall your system or provision a new one. In this blog post, I will talk about how I manage my dotfiles. You are welcomed to check out my dotfiles on GitHub.

At my first attempt to manage my dotfiles, I tried to create symlinks of various dotfiles into the git repo. I quickly realize it’s a no go because git will simply store the symlink, not the actual file content. Therefore, if I don’t want to maintain two copies of the same file and worry about things not being synced, I must store the actual file inside the git repo and create the symlink inside my home directory. While doing this, I discovered the stow program. The idea is very simple. Suppose you have /a/b/c, if you stow c under /a/b, directory c will appear under /a (which is /a/b’s parent directory) as a symlink. Therefore, you can utilize it to manage you dotfiles!

$ cd ~ && mkdir .dotfiles && cd .dotfiles
$ mkdir zsh && touch zsh/.zshrc
$ stow zsh
$ ls -la ~/.zshrc
lrwxrwxrwx 1 koallen koallen 20 Jul 16  2018 /home/koallen/.zshrc -> .dotfiles/zsh/.zshrc

Making it even better

The stow program is nice, but using it alone is not really perfect for managing dotfiles. There are a few problems.

First, if you have neovim/.config/nvim/init.vim to stow and you don’t have ~/.config, the whole ~/.config folder will be symlinked. This means that anything later created under ~/.config will appear in your git repo! To solve this issue, I have to ensure ~/.config exists before I do the stow. I have written an script to help me stow all dotfiles and this check is done in my script.

Second, nowadays people use plugin managers to install plugins for programs like vim and tmux. Therefore, simply copying a dotfile may not be sufficient to fully configure the program. Most of the time you would need to git clone the plugin manager itself first, and then run some command to install the plugins defined in your dotfile. Therefore, I added a program-local script under each subdirectory in my repo. To avoid the script being stowed as well, I added it into the .stow-local-ignore file.


Managing dotfiles is essential in creating an easily reconfigurable command line environment, and stow is nicely suited for this purpose. With all the “enhancements” I added, this approach should provide with you a seamless experience in managing your dotfiles.


comments powered by Disqus