# How to Use Stow to Manage Dotfiles in the issmirnov Repository > Learn to manage your dotfiles using GNU Stow in the issmirnov repository. Create portable, version-controlled configurations easily without complex scripts. - Repository: [Ivan Smirnov/dotfiles](https://github.com/issmirnov/dotfiles) - Tags: how-to-guide - Published: 2026-03-04 --- **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: ```bash 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: ```bash 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: ```bash 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: ```bash 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`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml). You can bypass this entirely and use Stow instead by modifying the script: ```bash #!/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: ```bash 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: ```bash 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`](https://github.com/issmirnov/dotfiles/blob/main/zsh/config/paths.zsh) and need to refresh the symlinks: ```bash 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: ```bash 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 ` 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`](https://github.com/issmirnov/dotfiles/blob/main/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`](https://github.com/issmirnov/dotfiles/blob/main/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.