#linux #utility #configuration

Understanding stow

GNU Stow can be described as a symlink farm manager, it can mirror the structure of one directory into another by creating symbolic links back to the original files.

This is extremely useful when you have a directory full of configuration files that is managed by git and you want to send all of those configuration files to where they belong in your home directory.

Few important concepts to understand. Can find them in Terminology documentation.

This is how it looks in practice:

target-directory
    stow-directory
        package-1
            .dotfile1
        package-2
            .dotfile2
            .dotfile3

$HOME           --->    (target-directory)
    dotfiles    --->    (stow-directory)
        bash    --->    (package)
            .bashrc     (dotfile)
            .bash_aliases
        git
            .gitconfig

By default stow ignores some files and directories but you can set your own rules by creating the .stow-local-ignore file

Common Use Cases

While still useful for its original purpose, the most popular use for GNU Stow today is managing "dotfiles" – the configuration files that often start with a dot (e.g., .bashrc, .vimrc) and reside in your home directory. By keeping your dotfiles in a version-controlled directory (like a Git repository), you can easily sync your configurations across multiple machines.

Other uses include:

Getting Started

Installation

GNU Stow is available in the package managers of most Linux distributions and on macOS via Homebrew.

Creating Your Dotfiles Directory

The most common setup involves creating a directory in your home folder to store your dotfiles. A common convention is to name it .dotfiles.

mkdir ~/.dotfiles
cd ~/.dotfiles

Inside this directory, you will create subdirectories for each "package" of configuration files you want to manage. For example, you might have separate directories for bash, vim, and git.

A best practice is to keep configurations for different applications in separate packages to make them easier to manage.

How Stow Works: An Example

Let's say you want to manage your .bashrc file.

  1. Create a package directory: Inside your .dotfiles directory, create a directory for your bash configuration.

    mkdir -p ~/.dotfiles/bash

  2. Move your configuration file: Move your .bashrc file into this new directory.

    mv ~/.bashrc ~/.dotfiles/bash/

  3. Stow the package: From within your .dotfiles directory, run the stow command.

    cd ~/.dotfiles
stow bash

Stow will see the bash directory and create a symbolic link from ~/.bashrc to ~/.dotfiles/bash/.bashrc.

The key principle is that Stow mirrors the directory structure. If a file needs to be in a subdirectory of your home directory, you must replicate that structure within your package directory. For example, if you have a configuration file at ~/.config/nvim/init.vim, your Stow package structure would look like this:

~/.dotfiles/nvim/.config/nvim/init.vim

When you run stow nvim from ~/.dotfiles, Stow will create the necessary directories and symlinks.

Essential Stow Commands

Using Stow with Git

The real power of this approach comes when you combine it with Git.

  1. Initialize a Git repository: In your .dotfiles directory, initialize a new Git repository.

    cd ~/.dotfiles
git init

  2. Add and commit your files:

    git add .
git commit -m "Initial commit of my dotfiles"

  3. Push to a remote repository: You can then push your dotfiles to a platform like GitHub or GitLab. This serves as a backup and allows you to easily clone your dotfiles onto a new machine.

When you set up a new machine, you can simply clone your .dotfiles repository and then use stow to create all the necessary symbolic links.

Ignoring Files

Stow will ignore certain files by default, such as .git. You can create a .stow-local-ignore file in your stow directory to specify additional files or patterns that you don't want Stow to manage.

read more