GNU Stow Management

Learn how to manage dotfiles using GNU Stow in the Kanagawa configuration

What is GNU Stow?

GNU Stow is a symlink farm manager that makes managing dotfiles incredibly simple. Instead of manually copying configuration files to their destinations, Stow creates symbolic links from a central repository to your system directories.

Why Use Stow?

• Version Control: Keep all your dotfiles in one git repository
• Easy Backup: Just backup your dotfiles directory
• Clean Uninstall: Remove all configs by unstowing
• Selective Installation: Install only what you need
• No File Duplication: Uses symlinks, not copies

Repository Structure

The Kanagawa dotfiles repository is organized specifically for Stow:

~/dotfiles/
├── config/           # Maps to ~/.config/
│   ├── hypr/
│   ├── waybar/
│   ├── ghostty/
│   ├── nvim/
│   ├── wofi/
│   ├── swaync/
│   ├── btop/
│   ├── cava/
│   ├── fastfetch/
│   └── zellij/
├── scripts/          # Maps to ~/.local/bin/
│   ├── theme-switcher
│   ├── theme-selector
│   └── weather
├── shell/            # Maps to ~/
│   └── .zshrc
└── install.sh        # Installation script

Each top-level directory in the repository represents a stow package. The directory structure inside each package mirrors where files should be linked on your system.

How the Install Script Works

The install.sh script automates the stow process:

#!/bin/bash

# Colores para la terminal
GREEN='\033[0;32m'
NC='\033[0m'

echo -e "${GREEN}Iniciando instalación de dotfiles... ${NC}"

# Crear carpeta .config si no existe
mkdir -p ~/.config
mkdir -p ~/.local/bin

# stow -v (verbose) -R (recursive) -t (target)
# Linkeamos lo que hay dentro de la carpeta 'config' a ~/.config
stow -v -R -t ~/.config config
stow -v -R -t ~/.local/bin scripts

# Linkeamos lo que hay en 'shell' al HOME
stow -v -R -t ~ shell

echo -e "${GREEN}¡Todo listo! Enlaces creados.${NC}"

Command Breakdown

1. Create directories

   mkdir -p ~/.config
   mkdir -p ~/.local/bin
   

   Ensures target directories exist before stowing

2. Stow config files

   stow -v -R -t ~/.config config
   

   • -v: Verbose output (shows what’s being linked)
   • -R: Restow (removes old links and creates new ones)
   • -t ~/.config: Target directory
   • config: Package name to stow
3. Stow scripts

   stow -v -R -t ~/.local/bin scripts
   

   Links scripts to ~/.local/bin for command-line access

4. Stow shell config

   stow -v -R -t ~ shell
   

   Links shell configurations (like .zshrc) to your home directory

Manual Stow Commands

You can also use stow commands directly:

Install/Update Configurations

# Stow all packages
cd ~/dotfiles
stow -v -R -t ~/.config config
stow -v -R -t ~/.local/bin scripts
stow -v -R -t ~ shell

# Stow a single package
stow -v -t ~/.config config

Remove Configurations

# Unstow (remove symlinks) for all packages
cd ~/dotfiles
stow -D -t ~/.config config
stow -D -t ~/.local/bin scripts
stow -D -t ~ shell

# Unstow a single package
stow -D -t ~/.config config

Check What Would Be Done

# Dry run (no actual changes)
stow -n -v -t ~/.config config

Adding New Configurations

To add a new application configuration to your dotfiles:

1. Create the directory structure

   cd ~/dotfiles/config
   mkdir -p your-app
   
2. Copy your config files

   # Copy existing config to dotfiles
   cp ~/.config/your-app/config.conf ~/dotfiles/config/your-app/
   
3. Remove original and stow

   # Remove original (backup first!)
   rm -rf ~/.config/your-app
   
   # Restow to create symlink
   cd ~/dotfiles
   stow -v -R -t ~/.config config
   
4. Verify the symlink

   ls -la ~/.config/your-app
   # Should show: your-app -> ../dotfiles/config/your-app
   

Example: Adding Kitty Terminal

cd ~/dotfiles/config
mkdir -p kitty
cp ~/.config/kitty/kitty.conf kitty/
rm -rf ~/.config/kitty
cd ~/dotfiles
stow -v -R -t ~/.config config

Removing Configurations

To temporarily remove a configuration without deleting it:

# Unstow just that package
cd ~/dotfiles
stow -D -t ~/.config config

# Or manually delete the symlink
rm ~/.config/app-name

To permanently remove:

# Unstow first
stow -D -t ~/.config config

# Then remove from repository
rm -rf ~/dotfiles/config/app-name

# Commit the change
git add -A
git commit -m "Remove app-name configuration"

Troubleshooting Stow

Stow will refuse to create links if:

• Target files already exist (not symlinks)
• Directory structure conflicts exist
• You don’t have write permissions

Common Issues

Error: “WARNING! stowing config would cause conflicts”

This means files already exist at the target location.

# Backup existing config
mv ~/.config/hypr ~/.config/hypr.backup

# Then stow again
stow -v -R -t ~/.config config

Error: “Target already exists”

A non-symlink file/directory exists at the target.

# Check what's there
ls -la ~/.config/app-name

# If it's not a symlink, backup and remove
mv ~/.config/app-name ~/.config/app-name.backup

Checking Symlink Status

# See if a directory is a symlink
ls -la ~/.config/hypr
# Output: hypr -> ../../dotfiles/config/hypr

# Find all symlinks in .config
find ~/.config -type l -ls

Best Practices

Use Git

Always version control your dotfiles repository

cd ~/dotfiles
git add -A
git commit -m "Update config"
git push

Test Before Committing

Verify configs work before committing

# Test the config
hyprctl reload

# If good, commit
git commit -am "Update Hyprland config"

Use Branches

Test major changes in branches

git checkout -b test-new-config
# Make changes
git checkout main

Document Changes

Add comments to complex configurations

# Custom keybinding for theme switcher
bind = $mainMod SHIFT, return, exec, theme-selector

Advanced: Selective Stowing

You can stow individual subdirectories if needed:

# Only stow Hyprland config
cd ~/dotfiles/config
stow -v -t ~/.config hypr

# Only stow Waybar config  
stow -v -t ~/.config waybar

This is useful when testing configurations for a single application without affecting others.

Next Steps

Adding Themes

Learn how to add custom color themes

Customization

Customize keybindings, fonts, and more