Managing Dotfiles with GNU Stow and Git

1. What is GNU Stow?

GNU Stow is described as a "symlink farm manager" on its homepage, which is true, but feels a bit underwhelming. Rather, I'd describe it as a tool to systematically and logically link, organize, and version control any files on your system.

2. Installation

First things first: let's install Stow. I'm on macOS, so I run the following command:

brew install stow

To ensure it's installed correctly, check the version:

stow -V

3. Stow Dotfiles

Next, let's create a directory to use as the central source for all these files. In my case, I store all git repositories in my ~/git/ directory, so I will create a dotfiles directory here:

# Create the dotfiles repository
mkdir ~/git/dotfiles && cd ~/git/dotfiles

Next, let's stow our first set of dotfiles. We'll use zsh as an example here. To do this, we will:

1. Create a directory for Zsh.
2. Move our current Zsh configuration files into our Stow directory.
3. Use Stow to symlink the files back into our home directory.

# Create the ZSH Stow directory
mkdir zsh                          && \
# Move your ZSH files into Stow
mv ~/.zshrc ~/git/dotfiles/zsh/    && \
mv ~/.zprofile ~/git/dotfiles/zsh/ && \
# Use Stow to symlink them back to your user home
stow zsh

By default, Stow will symlink your files (e.g., zsh) to the parent directory of the directory in which you execute the command. Since we're in the ~/git/dotfiles directory, we need to modify our stow command to ensure Stow symlinks the files to our home directory:

stow -t ~ zsh

At this point, you have a centralized directory (/git/dotfiles) where you can stow any file and use stow to symlink it back to another directory on your system.

Therefore, you only need to navigate to this directory to make changes across your system.

4. Update Dotfiles

When you make changes to your Stow directory, you can inform Stow and have the program update its symlinks with the following command:

cd ~/git/dotfiles && \
stow -R zsh

To summarize:

Action	Command	Why?
Edited a file	None (Just save)	The symlink already exists.
Added a file to existing folder	stow -R <package>	To create the new symlink for that file.
Deleted a file from dotfiles	stow -R <package>	To remove the "dead" symlink from your home dir.
Created a whole new package	stow <package>	To link the new directory for the first time.

5. Save to a Git Repository

Lastly, let's finish the puzzle by ensuring that this configuration is long-lasting and can transfer amongst systems.

To this end, we will use Git as our VCS. You can simply create the repository, add your files, and push to your remote.

git init                       && \
git add .                      && \
git commit -m "initial commit" && \
git remote add origin GIT_URL  && \
git push

If you want to automate this even more, write an alias or a hook into your stow command to automatically commit your changes whenever they occur.

At this point, I have organized and managed my dotfiles much more efficiently and no longer lose them whenever I wipe my machines.

...or, comment on this post on Bubbles!