# 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](https://omarchy.org/) on a spare [Beelink Mini PC](https://amzn.to/3KB0wVp) 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](https://www.gnu.org/software/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](https://ghostty.org/) 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

```bash
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:

```bash
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`:

```bash
mv ~/.config/ghostty/config ~/dotfiles/ghostty/.config/ghostty/
```

If there are additional files:

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

### 4. Clear out the live config folder

```bash
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:

```bash
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

```bash
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:

```bash
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!