| name | gnu-stow |
| description | Invoke GNU Stow to manage symlink farms — stow, restow, unstow, and simulate package deployment. Use when running stow commands, deploying dotfiles via symlinks, fixing stow conflicts, understanding -d/-t flags, restow after file changes, unstow with -D, dry-run with -n, or .stow-local-ignore rules — even if the user only says "symlink config" or "install package to home" without naming Stow.
|
| license | MIT |
| metadata | {"author":"j-shilling","version":"0.1.0"} |
| allowed-tools | ["bash","read"] |
GNU Stow CLI
GNU Stow creates symlinks from a stow directory (package trees) into a target directory (e.g. $HOME). It is not git — it does not track history; it only manages symlinks.
Terminology
| Term | Flag | Meaning |
|---|
| Stow directory | -d DIR | Root containing package subdirectories |
| Target directory | -t DIR | Where symlinks are created |
| Package | (positional) | Top-level subdirectory name under stow dir |
Always pass -d and -t explicitly. Defaults (cwd = stow dir, target = parent of stow dir) are error-prone.
Command template
stow -d <stow-dir> -t <target-dir> [options] [action] <package>...
Example:
stow -d ~/dotfiles -t "${HOME}" --no-folding -v -R emacs
Choose an action
| Goal | Flag | Command fragment |
|---|
| First install | -S (default) | stow -d DIR -t TARGET -S pkg |
| Update after package edits | -R | stow -d DIR -t TARGET -R pkg |
| Remove symlinks from target | -D | stow -d DIR -t TARGET -D pkg |
| Preview without changes | -n | stow -n -d DIR -t TARGET -R pkg |
Prefer -R (restow) after adding, removing, or renaming files inside a package. Restow unstows then stows again, pruning obsolete symlinks.
Recipes
Stow one package (first install)
stow -d ~/dotfiles -t "${HOME}" --no-folding -v emacs
Restow after editing package files
stow -d ~/dotfiles -t "${HOME}" --no-folding -v -R emacs
Unstow (remove symlinks from target)
stow -d ~/dotfiles -t "${HOME}" --no-folding -v -D emacs
Unstow only removes symlinks Stow owns. It never deletes files inside the package directory.
Dry-run (simulate)
stow -n -d ~/dotfiles -t "${HOME}" --no-folding -v -R emacs
Use -n before -D or when diagnosing conflicts.
Verify symlinks
readlink ~/.config/emacs/init.el
ls -la ~/.config/emacs/init.el
Expected: symlink pointing into the stow directory (relative path into package tree).
Flags you must know
--no-folding
Disable tree folding. Without it, Stow may symlink an entire subtree (e.g. ~/.config → one package's .config). Use --no-folding when multiple packages share parent directories (typical dotfiles layout: emacs, git, agents all under ~/.config/).
-v / --verbose
Print operations to stderr. Levels 0–5; -v increments by one, --verbose=N sets level.
Do not use casually
--adopt: moves existing real files into the package tree. Destructive to layout; only when user explicitly requests.- Default paths: never omit
-d/-t unless you have verified cwd and target.
Gotchas
- Not git — stow manages symlinks only; version control is separate.
- Never deletes package trees — unstow removes target symlinks, not source files in the stow directory.
- Conflicts abort cleanly — since Stow 2.0, conflicts are detected before any changes; the filesystem is left untouched on failure.
- Conflict causes — a real file or non-Stow directory already exists where Stow needs a symlink.
- Ignore lists —
.stow-local-ignore in each package root excludes paths from stowing (Perl regexes, one per line).
--dotfiles — maps dot- prefix to . (e.g. dot-bashrc → .bashrc). Only needed when packages use that naming convention.
Deep reference
For full option tables, tree folding, ignore-list matching rules, and conflict details, read references/stow-cli.md.
For live version-specific lookup, use the unix-manuals skill (skills/unix-manuals/SKILL.md).
Official docs: man stow, info stow, GNU Stow manual.
