Skip to main content
GNU Stow is a symlink farm manager that makes it easy to manage dotfiles. Instead of copying configuration files to your home directory, Stow creates symbolic links, allowing you to keep all your dotfiles in a single Git repository.

​
How Stow works

Stow operates on the concept of “packages”. In this dotfiles repository, the entire directory is treated as a single package, with the repository root representing your home directory structure. When you run Stow, it:
  1. Traverses the package directory
  2. Creates symbolic links in the parent directory (your home directory)
  3. Mirrors the directory structure
  4. Skips files listed in .stow-local-ignore
Stow creates links from your home directory to the files in your dotfiles repository. This means you can edit files in place, and changes are immediately tracked by Git.

​
Basic usage

​
Installing dotfiles

From your dotfiles repository directory: 
stow .
This command creates symlinks in your home directory for all files and directories in the current directory.
The . (dot) refers to the current directory. You can also specify the directory explicitly: stow /path/to/dotfiles

​
Removing dotfiles

To remove all symlinks created by Stow: 
stow -D .
The -D flag (delete) removes symlinks but preserves the files in your dotfiles repository.

​
Restowing dotfiles

If you’ve added new files or changed the structure: 
stow -R .
The -R flag (restow) first removes existing symlinks, then creates new ones. This is useful after pulling updates.

​
Dry run

To see what Stow would do without making changes: 
stow -n .
or for more verbose output: 
stow -nv .

​
Ignore patterns

The .stow-local-ignore file specifies patterns for files and directories that Stow should skip when creating symlinks.
.stow-local-ignore
# Version control
RCS
.+,v
CVS
\.\.#.+       # CVS conflict files / emacs lock files
\.cvsignore
\.svn
_darcs
\.hg
\.git
\.gitignore
\.gitattributes
\.gitmodules

# Editor backup files
.+~          # emacs backup files
\#.*\#       # emacs autosave files

# Documentation and licenses
^/README.*
^/LICENSE.*
^/COPYING

# Custom exclusions
.*\.ttf
install.sh
The patterns use regular expressions. The ^/ prefix matches files only at the repository root, while patterns without it match anywhere in the tree.

​
Common exclusions explained

Files like .git, .gitignore, and .gitmodules are excluded because they’re used for repository management and shouldn’t be symlinked to your home directory.
Documentation files at the repository root (^/README.*, ^/LICENSE.*) are excluded since they’re for the repository itself, not part of your system configuration.
The installation script is excluded because it’s a helper script for setting up the dotfiles, not a configuration file to be linked.
Font files are excluded because they should be installed to the system font directory rather than symlinked from the dotfiles repository.

​
Troubleshooting

​
Existing files conflict

If Stow encounters existing files that aren’t symlinks, it will abort with an error: 
WARNING! stowing . would cause conflicts:
  * existing target is not owned by stow: .bashrc
1

Backup the existing file

mv ~/.bashrc ~/.bashrc.backup
2

Run Stow again

stow .
3

Merge any custom configurations

Compare the backup with the new symlinked file and merge any custom settings.
To find broken symlinks in your home directory: 
find ~ -maxdepth 3 -type l ! -exec test -e {} \; -print
Remove broken symlinks: 
find ~ -maxdepth 3 -type l ! -exec test -e {} \; -delete
Be careful with the -delete flag. Always run without -delete first to review what will be removed.
To check if a file is a symlink and where it points: 
ls -la ~/.config/kanata/config.kbd
The output will show the symlink arrow: 
lrwxrwxrwx 1 user user 45 Mar 2 10:00 .config/kanata/config.kbd -> /home/user/dotfiles/.config/kanata/config.kbd

​
Advanced usage

​
Stow with different target directory

By default, Stow uses the parent directory as the target. To specify a different target: 
stow -t /custom/target/directory .

​
Multiple packages

You can organize dotfiles into multiple packages and stow them selectively: 
# Repository structure:
# dotfiles/
#   shell/
#     .bashrc
#     .zshrc
#   editor/
#     .config/nvim/

# Stow only shell configs
cd dotfiles
stow shell

# Stow only editor configs
stow editor

​
Adopting existing files

The --adopt flag moves existing files into your dotfiles repository and replaces them with symlinks: 
stow --adopt .
This modifies files in your dotfiles repository. Review changes with git diff before committing.

​
Integration with the install script

This dotfiles repository includes an install.sh script that automates the Stow process along with other setup steps. See the Installation guide for details.

Installation

Set up the dotfiles with the install script

GNU Stow manual

Official GNU Stow documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us