Managing dotfiles with Stow

2021-08-16 3 min read

Dotfiles are plain-text configuration files with a . at the beginning of their filename which makes them hidden. These files may be configuring your git tool, or functions you use in the shell, or something else.

Stow and dotfiles

If you're on a GNU/Linux distribution or similar, you already have many dotfiles. For example, check the ~/.bashrc file, or ~/.gitconfig if any. As you make your own changes to these files, you will want to be able to keep and manage these changes. The Stow tool helps me a lot in this regard and I can manage my dotfiles with a version control system such as git.

How to install Stow


pacman -S stow


apt-get install stow

How to use Stow

It's simple. Let's go through an example. We want to manage our SSH related configuration files. We can find these files in the ~/.ssh folder.

First, create a folder named dotfiles, and another folder named ssh in it. Now copy your ~/.ssh folder with its content to this new ssh folder, excluding your private files you don't want to expose in your VCS. You'll have a folder hierarchy like this:

└── ssh
    └── .ssh
        └── config

Now our ssh module can be managed with Stow. Move this dotfiles folder to where you want to keep all your dotfiles. Remember that if you want to use Stow without specifying a target directory, you need to keep the dotfiles directory in your home directory. I keep it as a hidden folder in my home directory for easy use: ~/.dotfiles. After taking a backup of your .ssh folder, delete it for testing. Run the following command in the ~/dotfiles directory:

$ stow ssh

# or if your `dotfiles` folder is not in your home directory:
$ stow -t ~/ ssh

With this command, Stow creates symbolic links in your home directory, preserving the folder structure. What just happened is that you now have a ~/.ssh folder again, but this time with symlinks to the ~/dotfiles directory. So the actual files are in ~/dotfiles:

$ ls -la ~/.ssh
drwx------  2 user user 4096 Nov 12 16:50 .
drwx------ 44 user user 4096 Nov 12 16:50 ..
lrwxrwxrwx  1 user user   28 Nov 12  2021 config -> ../dotfiles/ssh/.ssh/config

When you switch to a new computer, all you have to do is to transfer your dotfiles folder to this computer and stow the modules you want with the stow command.

Whatever you put inside the folders (modules) you created in the dotfiles folder, the Stow tool will create symbolic links to them in the parent directory by default, preserving the folder structure. That's all. You can change the default target directory with the -t DIR, --target=DIR option.

Date: 2021-08-16
Categories: gnu linux