Manage Your Dotfiles with GNU Stow

A clean, repeatable way to manage dotfiles using symlinks.

Why GNU Stow

• Keeps your home directory tidy by symlinking files from a single repo
• Easy to enable/disable sets of configs (“packages”)
• Repeatable across machines (just clone and stow)

Prerequisites

# Debian/Ubuntu
sudo apt install stow

# macOS (Homebrew)
brew install stow

Initialize the Dotfiles Repo

mkdir -p ~/.dotfiles
cd ~/.dotfiles
git init

Organize by “Packages”

Create one folder per tool. Inside each, mirror the path from your home directory.

Example layout:

~/.dotfiles/
  bash/
    .bashrc
    .bash_aliases
  vim/
    .vimrc
  git/
    .gitconfig

Move your existing files into the matching package folders above (e.g., move ~/.vimrc to ~/.dotfiles/vim/.vimrc).

Symlink with Stow

From inside ~/.dotfiles:

# Preview (dry run) to see what will be linked
stow -nv bash vim git

# Apply the symlinks
stow bash vim git

Notes:

• By default, running stow inside ~/.dotfiles targets the parent directory (~).
• To target a specific directory: stow -t ~ bash

Update, Unstow, Restow

# Unlink a package
stow -D git

# Restow (relink) after changes
stow -R bash

Ignore Files

Create a .stow-local-ignore file in a package to skip files you don’t want symlinked (e.g., README.md, local notes).

Example .stow-local-ignore:

^README\.md$
^notes/

Version Control and Secrets

• Commit your dotfiles to Git for portability.
• Avoid committing secrets; keep machine-specific or secret files out of the repo (use .gitignore or a separate “local” package you don’t sync).

Quick Start Summary

mkdir -p ~/.dotfiles && cd ~/.dotfiles
mkdir bash vim git

# Move existing files into the package structure:
# mv ~/.bashrc ~/.dotfiles/bash/.bashrc
# mv ~/.vimrc ~/.dotfiles/vim/.vimrc
# mv ~/.gitconfig ~/.dotfiles/git/.gitconfig

stow -nv bash vim git   # preview
stow bash vim git       # link

That’s it—your configs are now cleanly managed and easy to replicate.