How to Use Stow to Manage Dotfiles in the issmirnov Repository

GNU Stow creates symlinks from the issmirnov/dotfiles repository's top-level directories directly into your home folder, enabling portable, version-controlled configuration management without complex install scripts.

The issmirnov/dotfiles repository stores user configuration files in a flat, top-level layout specifically designed for GNU Stow. Each directory represents a self-contained package that maps cleanly to your home directory, allowing you to manage stow dotfiles with simple commands instead of manual symlink creation.

Why This Repository Structure Works with Stow

The repository organizes configurations into distinct application folders such as zsh/, vim/, i3/, git/, and onagre/. This directory-per-application approach allows Stow to treat each folder as a package and create the required symlinks under $HOME.

Files like zsh/zshrc, vim/vimrc, and git/config are stored exactly as they should appear in the target. When you run Stow, it reproduces these relative paths in your home directory, creating links such as ~/.zshrc → ~/.dotfiles/zsh/zshrc and ~/.vimrc → ~/.dotfiles/vim/vimrc.

Installing Stow and Cloning the Repository

First, install GNU Stow using your package manager. On Debian or Ubuntu systems, run sudo apt-get install stow. For macOS, use Homebrew with brew install stow.

Clone the repository into a dedicated directory and navigate to it:

git clone https://github.com/issmirnov/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

Stowing Individual Packages

To activate a specific configuration package, use the -t flag to set your home directory as the target. For example, to install the Zsh configuration from the zsh/ directory:

stow -t $HOME zsh

This command creates a symlink at ~/.zshrc pointing to ~/.dotfiles/zsh/zshrc. The same operation links any additional files found under the zsh/ directory tree into corresponding locations in your home folder.

Managing Multiple Packages

You can install several configurations simultaneously by listing multiple directory names. To set up Zsh, Vim, Git, and i3 window manager configurations at once:

stow -t $HOME zsh vim git i3

Each package is processed independently, creating all necessary symlinks without conflicts between directories.

To remove a package and delete its symlinks, use the -D (delete) flag:

stow -D -t $HOME zsh

Essential Stow Options for Dotfiles

Understanding these common flags helps you manage your stow dotfiles workflow effectively:

• -t $HOME – Explicitly sets the target directory to your home folder, overriding the default current working directory.
• -R – Restows a package by first unstowing then stowing again, useful after editing files inside the package directory.
• -v – Verbose mode shows each symlink creation and deletion as it happens.
• -n – Dry run simulates the operation without writing anything to the filesystem, letting you preview changes safely.

Replacing the Dotbot Install Script

The repository includes an install script that currently invokes dotbot to perform linking via default.conf.yaml. You can bypass this entirely and use Stow instead by modifying the script:

#!/usr/bin/env bash
set -e

# Existing submodule preparation (unchanged)

git submodule update --init --recursive

# Replace dotbot linking with Stow

cd "$(dirname "$0")"   # repository root

stow -t $HOME -R zsh vim git i3   # restow all core packages

This approach keeps any OS-specific actions from the original script while using Stow for the linking step.

Handling Local Overrides and Custom Files

Some configurations in this repository support local overrides, such as ~/.zshrc.local for machine-specific Zsh settings. Stow does not manage these override files automatically.

After running Stow, simply create the local file in your home directory. It will shadow the symlinked version, allowing you to maintain sensitive or machine-specific data outside of version control.

Best Practices for Stow Dotfiles Management

Keep your repository clean and conflicts minimal by following these guidelines:

• Commit only the symlink-free source – Ensure version control tracks only the files inside the repository, not the generated symlinks in your home directory.
• Maintain package independence – Avoid cross-references between top-level directories to prevent circular symlinks and dependency issues.
• Use a .stowrc file – Create a .stowrc file in your repository root containing target = $HOME to omit the -t $HOME flag from every command.

Practical Stow Examples

Installing the Full Dotfiles Set

Clone the repository and install all core packages in one command:

git clone https://github.com/issmirnov/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
stow -t $HOME -v zsh vim git i3 onagre

The -v flag displays each symlink creation, confirming that files like vim/vimrc correctly map to ~/.vimrc.

Adding a New Package (tmux)

Create a new directory structure for tmux and add your configuration file:

mkdir tmux
mv ~/.tmux.conf tmux/tmux.conf
stow -t $HOME tmux

This creates ~/.tmux.conf → ~/.dotfiles/tmux/tmux.conf without disturbing existing configurations.

Updating After Edits

If you modify zsh/config/paths.zsh and need to refresh the symlinks:

stow -R -t $HOME zsh

The -R flag ensures Stow removes old links and creates new ones reflecting your current file state.

Dry-Run Verification

Before committing changes to your filesystem, preview what Stow would do:

stow -n -t $HOME -v i3

This outputs every planned symlink operation without actually creating them, helping you catch path errors before they affect your system.

Summary

• The issmirnov/dotfiles repository uses a flat directory structure where each top-level folder (like zsh/, vim/, git/) represents a Stow package.
• Run stow -t $HOME <package> to create symlinks from the repository to your home directory.
• Use -D to remove packages, -R to restow after changes, and -n for dry runs.
• Local override files (like .zshrc.local) shadow symlinked configurations without requiring Stow management.
• You can replace the existing dotbot-based install script with direct Stow commands for simpler, more transparent dotfiles management.

Frequently Asked Questions

What happens if a target file already exists in my home directory?

Stow will refuse to overwrite existing files and display an error message. You must manually move or delete the conflicting file (such as an existing ~/.zshrc) before Stow can create the symlink to zsh/zshrc. This safety mechanism prevents accidental destruction of existing configurations.

Can I use Stow alongside the existing install script?

Yes, but avoid running both simultaneously for the same packages. The install script uses dotbot with default.conf.yaml to create links, while Stow manages them independently. Choose one method per package to prevent conflicts where Stow might see dotbot-created symlinks as obstructions, or vice versa.

How do I add a new configuration package to the repository?

Create a top-level directory named after the application (for example, tmux/). Place your configuration files inside using the same relative paths they should occupy in your home directory (so tmux/tmux.conf becomes ~/.tmux.conf). Then run stow -t $HOME tmux to activate the new package.

Does this approach work on both macOS and Linux?

Yes. GNU Stow functions identically on macOS (installed via Homebrew) and Linux distributions (installed via apt, yum, or pacman). The issmirnov/dotfiles repository structure remains compatible across both platforms because Stow relies only on standard symbolic link functionality present in all Unix-like operating systems.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}