stow

Symlink all files recursively to a given directory

$ stow [[-t|--target]] [path/to/target_directory] [file1 directory1 file2 directory2]

$ stow [[-D|--delete]] [[-t|--target]] [path/to/target_directory] [file1 directory1 file2 directory2]

$ stow [[-n|--simulate]] [[-t|--target]] [path/to/target_directory] [file1 directory1 file2 directory2]

$ stow [[-R|--restow]] [[-t|--target]] [path/to/target_directory] [file1 directory1 file2 directory2]

$ stow --ignore=[regex] [[-t|--target]] [path/to/target_directory] [file1 directory1 file2 directory2]

stow [options] [packages...]

Common usage:
stow [-D|-R|-S] [-v|-n] [-d stow_dir] [-t target_dir] [package]

-S, --stow
    Explicitly specifies the "stow" action (default). Creates symlinks from the package directory to the target directory.

-D, --delete
    Performs the "unstow" action. Deletes symlinks previously created by stow for the specified package(s).

-R, --restow
    Performs a "restow" action. First unstows the package(s), then stows them again. Useful for updating symlinks after changes in the source package.

-v, --verbose[=N]
    Increases verbosity level. Higher N (e.g., -v2, -v3) provides more detailed output.

-n, --no-act
    Performs a dry run. Shows what actions stow would take without actually modifying any files or creating symlinks.

-d, --dir=DIR
    Specifies the "stow directory" where packages are located. Defaults to the parent directory of the current working directory.

-t, --target=DIR
    Specifies the "target directory" where symlinks will be created. Defaults to the parent directory of the current working directory.

--dotfiles
    Enables special handling for dotfiles (files starting with a dot, e.g., .bashrc). It treats a directory named dotfiles as if its contents are directly in the target, and handles the dot in the symlink names.

--no-override
    Prevents stow from overriding existing files or directories in the target directory with symlinks.

--override=ENTRY
    Allows stow to override an existing file or directory with a symlink for a specific ENTRY (e.g., bin/ls). Can be specified multiple times.

--ignore=REGEX
    Specifies a regular expression for files or directories that should be ignored by stow and not linked. Can be specified multiple times.

--defer=REGEX
    Specifies a regular expression for files or directories that should not be symlinked directly, but whose subdirectories should still be processed.

stow is a powerful and flexible program that simplifies the management of software installations and configuration files using symbolic links. Instead of copying files directly into system directories, stow creates a "symlink farm" from a structured "stow directory" into a specified "target directory". Each software package or configuration set is placed in its own subdirectory within the stow directory. When a package is "stowed," stow intelligently creates symbolic links for all its contents (files and subdirectories) from the package's location to the corresponding paths within the target directory. This makes the installed software or configurations appear as if they were natively installed in the target location, while keeping the original source files organized and separate.

This approach is particularly valuable for managing dotfiles (configuration files like .bashrc or .vimrc in a user's home directory), allowing them to be version-controlled in a repository and easily deployed across multiple systems. It also facilitates installing multiple versions of the same software, or custom builds, without conflicting with system-wide installations or requiring root privileges for many use cases. stow promotes a clean, non-invasive installation method, making it straightforward to "unstow" (remove the symlinks) a package without leaving orphaned files.

stow is a powerful tool, but users should be aware of certain considerations:

Potential for Conflicts: If not used carefully, stow can conflict with existing files or directories in the target directory, especially if the --no-override option is not used. This can lead to unexpected behavior or data loss if critical system files are overwritten.

Dependency on Source Location: Since stow relies on symbolic links, moving or deleting the original package directories within the stow directory will break the created symlinks in the target directory, rendering the "installed" software unusable until the links are fixed or the package is re-stowed.

Not a Package Manager: stow is not a full-fledged package manager. It does not handle software dependencies, compilation, or automatic updates. It is primarily a symlink manager for pre-existing installations or source builds.

Complexity with Root: While often used without root, using stow in system-wide directories (like /usr/local) requires root privileges, and mistakes can impact system stability. It's generally safer for user-specific installations or in dedicated user directories.

At its core, stow operates on two main directories: the 'stow directory' (where your individual packages reside, each in its own subdirectory) and the 'target directory' (where stow creates symlinks). When you execute stow <package_name>, it inspects the contents of <stow_directory>/<package_name>. For every file or subdirectory found within, stow creates a corresponding symbolic link in the 'target directory'. For example, if you have <stow_directory>/myvim/.vimrc, and your target directory is your home directory (~), stow will create a symlink ~/.vimrc pointing to <stow_directory>/myvim/.vimrc. This allows you to manage entire application installations or sets of configuration files as self-contained units.

One of stow's most popular applications is dotfile management. Users often keep their configuration files (like .bashrc, .gitconfig, .vim/, etc.) in a version-controlled Git repository. By structuring this repository as a stow directory, they can easily deploy these dotfiles to any new system by simply cloning the repo and running stow commands. Another common use is for installing custom software or multiple versions of the same software locally without root privileges. Instead of installing into /usr/local, you can install a program into a directory like ~/opt/mypackage-1.0 and then use stow to make its binaries and man pages available in your ~/bin and ~/man directories, which are typically already in your PATH.

GNU Stow originated as a program to manage separate software packages installed under a common directory structure, typically /usr/local. Its design goal was to provide a simple, non-invasive way to install multiple independent software packages without them interfering with each other, particularly useful in environments where a traditional package manager wasn't feasible or desired for certain installations. It leverages the Unix filesystem's symbolic linking capabilities to achieve this "virtual" installation, allowing users to keep source trees and built binaries in isolated directories while still making them accessible from common system paths. Over time, its flexibility and simplicity led to its widespread adoption for managing personal configurations (dotfiles) and local development environments, where users want fine-grained control over their installed software versions.

ln(1), install(1), make(1), git(1)