Never Lose Your Configs Again

The What

You'd be forgiven for not knowing about GNU Stow, but once you know about it — you'll wonder why you haven't used it. After all, the project has been around for decades.

With any tool though, you need to know why it's important.

What problem does it solve for me?

The Why

Here are the scenarios you might be in that would make you reach for GNU Stow.

1. You've spent hours configuring your setup (I'm looking at you r/unixporn) and you want to make sure you never lose it.
2. You have multiple computers and you're tired of managing this yourself.
3. You think your setup is the best thing going and want to share it with the world.

In each of the above, you might find yourself tweaking your setup and it never being just right. It's like someone adjusting your car seat. Sure, you can try to get it to the same spot but it's never exactly the same.

GNU Stow can change all that. For your current machine and the one you haven't bought yet but have your eye on.

The How

GNU Stow is a symlink farm manager. Basically, GNU stow enables users to create/update/destroy symlinks on their systems very easily. It's almost like a wrapper for symlink operations.

Ok, so what is a symlink?

A symlink (symbolic link) in Linux is a special type of file that acts as a pointer to another file or directory. It allows you to create a shortcut or reference to the target file, enabling access from a different location without duplicating the actual data.

Typically, you create symlinks in a linux environment to access executable programs from a directory that is in your PATH. Let's say I have a program on my machine called ~/some_dir/executable.sh. I don't want to have to type the full address and executable file EVERY TIME I want to run this program. So I can create a symlink to make this easier for me.

ln -s ~/some_dir/executable.sh ~/exec.sh

☝️creates a symbolically linked file called _/exec.sh that is linked to /some_dir/executable.sh. Now, when I run exec.sh it will literally do the same thing as the original file, /some_dir/executable.sh.

The cool part about symlinks is if you change one of the files, the other one changes. they’re tied together, and this will come into play with gnu stow.

So let's get into stow.

GNU Stow and Git

The real power of GNU Stow comes when you pair it with a git repository full of your dotfiles. With this combination, you can clone your git repo onto any machine (mac os or linux), go to your cloned directory, run stow and you're off!

Here is a quick chart showing how this works.

Stow naming conventions

When stowing your dotfiles, you must adhere to a pretty strict naming convention. It can trip you up at first, but once you get the hang of it, it's really easy. Essentially, every dotfile on your system lives under a "package" name in stow. Then, within that package name, you need to re-create the directory (starting with the home dir) your dotfile lives within.

Let's create a Stow dir

A GNU Stow directory is nothing special. It's just a dir that holds our dotfiles with a special naming convention. So we can create a stow directory, let's say, like this mkdir ~/stow_directory.

Now we want to move our current dotfiles to this new directory, following the special naming syntax.

For example. ~/.zshrc needs to be created in your stow directory as stow_directory/zshrc/.zshrc. We create a new package called "zshrc" in our stow_directory by making a new zshrc dir. Then we move our dotfile to this new dir.

Our neovim config (living at ~/.config/nvim) can be moved to our stow directory under our nvim "package". That directory would look like this: stow_directory/nvim/.config/nvim.

Notice how we re-create the directory structure of our neovim configs.

At the end of the day, we want our directory structure to look something like this:

Notice how in our ~/dotfiles directory, we have "packages" and within each "package" is a re-creation of each dotfile's directory structure. (i.e. tmux.conf is under /dotfiles/tmux/.tmux.conf).

Now let's stow our files

Actually, using stow is much easier than explaining it. Once you have your dotfiles set up in our special naming convention, all you have to do is cd into your stow directory, and run commands.

stow * will recreate symlinks for ALL of the packages in your dir

stow <package_name> will recreate the symlinks for just that package.

For example, I can run stow nvim if I want to just symlink my nvim config. This is very helpful if you have one stow repository that you use for both mac os and linux. Surely, you don't need an i3/config on your Mac OS machine, right?

Typecraft Configs

Want to use our configs? Check out our repo here.

What's Next?

If you haven't already, get a github repo setup called dotfiles and commit your ~/dotfiles to it. Now you can move your configuration from computer to computer the next time you upgrade that sweet, sweet machine of yours.

And with that, never lose your configs again.