Syncing dotfiles across PCs with GNU Stow

Whether I’m on my old laptop, my shiny work machine, or even a random PC I’ve borrowed for a weekend, I want my tools, shortcuts, and configs to feel like home.

Bash, vim, terminal emulators, tmux, all those things that make your system yours.

Copying them over manually, dealing with version mismatches or forgetting where I stashed the latest tweaks? Yeah, that was a mess.

What’s Stow, anyway?

So, what’s this Stow that saved me from my dotfile nightmare? At its core, Stow is a tool for Linux that helps you manage files using symbolic links; think of them as shortcuts that point to where your actual files live.

"Symbolic links" might sound fancy or intimidating if you’re not familiar with them, but it’s really just a way to keep things tidy without copying files all over the place.

Instead of scattering my .bashrc, .vimrc, and other dotfiles across every machine I use, I keep them all in one neat folder. Then, Stow steps in and “links” them to the right places, like my home directory, so everything works as if I’d put them there myself. No more duplicating files or wondering which version is the latest.

For example, here is my configuration structure:

.
├── ghostty
│   └── .config
│       └── ghostty
│           └── config
├── ideavimrc
│   └── .ideavimrc
├── vimrc
│   └── .vimrc
├── bashrc
│   └── .bashrc
├── kitty
│   └── .config
│       └── kitty
│           └── kitty.conf
├── tmux
│   └── .config
│       └── tmux
│           └── tmux.conf
└── zsh
    └── .zshrc

Every folder in there is for a tool I use, like Kitty or Zsh, and I can put in one file, a couple of files, or even a whole subfolder. Stow grabs whatever’s inside and makes it work.

Getting started with Stow

Okay, so how do you actually use Stow to make this magic happen? First, you need Stow on your machine.

On most Linux systems it’s a quick install:

#Debian/Ubuntu
sudo apt-get install stow
#Fedora
sudo dnf install stow
#Arch Linux
sudo pacman -S stow

On macOS it’s available with brew:

brew install stow

Once it’s there, you’re ready to roll.

Setting up my dotfiles folder

Before Stow can work, you’ll need to organize your dotfiles. Start by creating a folder called dotfiles (I assume to place it in home directory, so the full path is ~/dotfiles).

Next, create a structure similar to the one shown above, with a separate folder for each tool. Ensure the file structure adheres to the following rule:

• Main directory (in this case dotfiles) is just the name of the container folder

• The subfolder should be named after the tool. While it's best to use the tool's actual name for clarity, you can choose any name to distinguish it. For example, you could name it foobar and Stow will still work correctly.

• Finally, the rest is the structure of your config files

Once you set it up you can cd into dotfiles directory and run stow:

cd dotfiles
stow kitty

Stow will locate the dotfiles/kitty directory, take its contents, and create symlinks in your home directory while preserving the same structure. For example, ~/dotfiles/kitty/.config/kitty/config will be symlinked as ~/.config/kitty/config.

If the .config folder doesn’t exist in my home directory, Stow will create it automatically. Pretty neat, right?

It might take a bit of time to get everything sorted, but once it’s done, you’ll have all your configs in one place, ready for Stow to link up. And trust me, it feels great to bring some order to that chaos!

Need to link all your configurations at once? No problem, Stow supports wildcard patterns:

stow * # Create symlinks for every tool

That’s it!

Managing your configs: Deleting and Adopting

So, you’ve got your dotfiles linked up with Stow, and everything’s running smoothly. But what if you want to undo one of those links, like, say, you’re done with your old Kitty setup and want to clean it out? Or maybe you’ve tweaked a config directly in your home directory and want Stow to take it over? No worries, Stow’s got you covered for both.

Deleting a linked configuration

To remove those symlinks, Stow offers a handy delete option. Just head to your ~/dotfiles folder in the terminal and run:

stow -D kitty

The -D flag tells Stow to delete the symlinks it created for the kitty folder. It will unlink ~/.config/kitty/kitty.conf (or whatever’s in there) without touching the original files in ~/dotfiles/kitty. Those stay safe in your dotfiles folder, so you can always bring them back later with a quick stow kitty if you change your mind.

It’s like hitting an undo button, simple and stress-free.

Adopting existing configs

Now, here’s a cool trick Stow can do: adopting configs you’ve already got in your home directory.

Picture this: you’ve been tweaking your .zshrc right in ~/.zshrc, but now you want it to live in your ~/dotfiles/zsh folder under Stow’s control. Instead of moving it manually, Stow can “adopt” it for you.

Here’s how it works. First, make sure your zsh folder exists in ~/dotfiles/ with the right structure, like ~/dotfiles/zsh/.zshrc, but leave it empty or with an older version. Then, from your ~/dotfiles directory, run:

stow --adopt zsh

What happens next is pretty slick. Stow sees the existing ~/.zshrc in your home directory, grabs it, and moves it into ~/dotfiles/zsh/.zshrc, replacing whatever was there. Then it creates a symlink back to ~/.zshrc, ensuring that everything continues to work as before.

It’s like Stow saying, 'Hey, I’ll take this off your hands and keep it organized for you'. Just be careful: if you already have a different .zshrc in ~/dotfiles/zsh already, it will get overwritten, so maybe back it up first if you’re not sure.

Wrapping it up

Stow takes the chaos of managing dotfiles and turns it into a simple, structured process, maybe even a little fun.

No more scrambling to copy configs between machines. No more version mismatches or lost tweaks. Just a clean, consistent setup that follows you wherever you go.

Setting up the structure takes a bit of effort upfront, but once it’s in place, you’ll wonder how you ever managed without it.