Managing Dotfiles with GNU Stow: Setup and Migration

Dotfiles – those crucial hidden configuration files that define your Linux environment – find their perfect management companion in GNU Stow, offering elegant symlink organization and effortless system migration through a simple setup process.

Why Stow?

Automatic symlink creation
Conflict resolution capabilities
Package-based organization
Cross-distribution compatibility

Getting Started with Stow

Installation

First, install Stow on your system:

1
2
3
4
5


# Debian/Ubuntu
sudo apt install stow -y

# Arch Linux (yay AUR helper)
yay -S stow --noconfirm

Initial Setup

Create a dedicated directory for your dotfiles (typically in your home directory) and initialize a Git repository:

1
2
3


mkdir ~/dotfiles
cd ~/dotfiles
git init

Organize your configuration files by application. For each program, create a folder that mimics the directory structure where the config files belong.

For example, for Neovim:

1
2


mkdir -p nvim/.config/nvim
mv ~/.config/nvim/init.lua nvim/.config/nvim/

Create a basic .gitignore file to exclude unnecessary files:

1
2


echo "*~" >> .gitignore
echo "*.swp" >> .gitignore

Commit your initial configuration:

1
2


git add .
git commit -m "Initial dotfiles commit"

To symlink your files to their proper locations:

1
2


stow . --adopt
git restore .

The --adopt flag tells Stow to adopt existing files, and git restore . helps clean up any conflicts if you’re using Git.

(Optional) Push to a remote repository:

1
2


git remote add origin https://github.com/yourusername/dotfiles.git
git push -u origin main

Handling Potential Conflicts

If files already exist in the target locations, you have several options:

Overwrite carefully (after backing up):

1

stow --override=* .

Adopt and compare changes:

1
2


stow --adopt .
# Then review differences before committing

Advanced Configuration

The .stowignore File

GNU Stow’s .stowignore file works similarly to .gitignore - it specifies files or patterns that Stow should ignore when creating symlinks.

Key Features

Pattern matching: Supports wildcards (*) and basic regex
Line-based: Each pattern goes on a separate line
Location-specific: Place in your package directory (e.g., ~/dotfiles/nvim/.stowignore)

Common Use Cases

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# Ignore temporary files
*.tmp
*.swp

# Ignore version control directories
.git/
.vscode/

# Ignore specific config files
local_settings.*

Restoring Dotfiles on a New System

One of the biggest advantages of this system is how easy it makes migrating to a new machine:

Clone or copy your dotfiles repository to the new machine:

1

git clone https://github.com/yourusername/dotfiles.git ~/dotfiles

Install Stow on the new system (as shown in the installation section above).
Navigate to your dotfiles directory and deploy all configurations:

1
2


cd ~/dotfiles
stow .

With this setup, you’ll never have to manually reconfigure your environment again.

Just clone and stow!

Dotfiles: Stow

My way to manage my dotfiles.