How to Manage Dotfiles with GNU Stow

Managing dotfiles can be tricky, especially when they span across various files and folders.

I recently set up Omarchy on a spare Beelink Mini PC that I had sitting around.

After customizing several Hyprland configuration files, dialing in my Ghostty terminal setup, and adjusting a handful of other tools, I decided it was finally time to bring these all together into an actual dotfiles, version-controlled, manageable, workflow with GNU Stow.

If you’ve ever tried manually managing symlinks, or worse, copying configs between machines, you know how chaotic it gets. GNU Stow solves this elegantly by letting you manage any dotfiles through a simple, mirrored folder structure.

In this guide, I’ll show you how to manage dotfiles using GNU Stow, using a Ghostty terminal configuration file as the example module. This same workflow works flawlessly for:

• Neovim
• Zsh
• Waybar
• Kitty / Ghostty
• Git configs
• Starship
• Mako
• Hyprland
• Fastfetch
  …and any other configuration under ~/.config or your home directory.

Once you understand the structure, Stow becomes one of the simplest and most powerful tools you can use to keep your Linux environment clean, reproducible, and easy to maintain.

Why Use GNU Stow for Dotfiles?

GNU Stow isn’t just a symlink tool, it’s a system for keeping your configurations:

• Clean
• Version-controlled
• Portable
• Easy to install on new machines
• Free of duplication or file drift

Most importantly, Stow prevents the classic dotfile nightmare:

“I have 10 copies of the same config and I don’t know which one I actually use.”

With Stow, you always know where your real configs live, in your single dotfiles repo, not scattered across your home directory.

The One Concept You Must Understand: Directory Mirroring

Stow works by mirroring directory structures.

If an application loads config files from:

~/.config/ghostty/

then your Stow module must contain:

~/dotfiles/ghostty/.config/ghostty/

Whatever exists inside that folder becomes symlinked back into the real config directory.

This folder mirroring is the key to understanding Stow.

Step-by-Step: Managing Dotfiles with GNU Stow

(Ghostty used as the example)

If you don’t already have it, install Stow with sudo pacman -S stow on Arch/Omarchy (or brew install stow on macOS). Once it’s installed, you can start using it to manage your dotfiles cleanly as discussed below.

Here’s the full workflow.

1. Create a dotfiles repository

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

2. Create a module folder for Ghostty

The module name can be anything, but using the program name keeps things clean:

mkdir -p ~/dotfiles/ghostty/.config/ghostty

This mirrors the real system path:

~/.config/ghostty

3. Move Ghostty config files into your repo

If Ghostty uses a file named config:

mv ~/.config/ghostty/config ~/dotfiles/ghostty/.config/ghostty/

If there are additional files:

mv ~/.config/ghostty/* ~/dotfiles/ghostty/.config/ghostty/

4. Clear out the live config folder

rm -rf ~/.config/ghostty/*

Don’t worry—your real files are safe in the repo now.

5. Use Stow to symlink the module

From inside your dotfiles repo:

cd ~/dotfiles
stow ghostty

Note the command is stow yourappname (essentially what goes before the .config in your path).

In runnign that command, Stow now creates:

~/.config/ghostty/config -> ../../dotfiles/ghostty/.config/ghostty/config

Ghostty loads the config exactly the same as before, but now it’s under version control. The symlink simply redirects Ghostty’s expected config path to the version stored in your dotfiles folder, so it never knows the difference.

6. Verify symlinks

ls -l ~/.config/ghostty

You should see arrows (->) showing symlink paths.

If you do, your setup is perfect.

Adding More Programs

Once you understand the pattern, adding modules becomes effortless.

For example:

Waybar

~/dotfiles/waybar/.config/waybar/

Neovim

~/dotfiles/nvim/.config/nvim/

Zsh

~/dotfiles/zsh/.config/zsh/

Git

If the config is in $HOME/.gitconfig:

~/dotfiles/git/.gitconfig

Then:

cd ~/dotfiles
stow git

Stow handles both .config folders and home directory dotfiles with ease.

Common Mistakes to Avoid

❌ Running Stow from ~/

This causes symlinks to scatter across your home directory.

Always run Stow from inside your dotfiles repo.

❌ Forgetting the mirrored folder structure

If the paths don’t match, Stow can’t place files correctly.

❌ Mixing real files and symlinks

Everything should either be real files inside your repo or symlinks in the live system.

Final Thoughts

GNU Stow is one of the cleanest, simplest, and most Git-friendly ways to manage dotfiles on Linux. Once you adopt the mirrored-folder workflow, you can scale your configuration management across:

• Multiple machines
• System rebuilds
• New dotfile additions
• Entire desktop environments

Using Ghostty as an example, this method works identically for any dotfile you want to manage.

Leave comments or questons below!