NAME

stow - manage software installation from the command-line

SYNOPSIS

stow [OPTION]... PACKAGE...

OPTIONS

Stow accepts the following options (listed alphabetically):

-c

--conflicts

Scan for and report conflicts. Unlike the -n option below, stow will not stop at the first observed conflict, but will carry on so as to report all possible conflicts. Note that stow's algorithm for determining what would happen is simplistic and will report conflicts in cases where none exists.

-d dir

--dir=dir

Use dir as the stow directory. If not specified, dir defaults to the current working directory.

-D

--delete

Unstow packages instead of stowing them. Stow is able to unstow a package even after the package has been deleted from the stow directory.

-h

--help

Print a short usage message and then exit.

-n

--no

Print the operations that would be performed but do not modify the filesystem. Like the -c option above, this option will report false conflicts in some circumstances.

-R

--restow

Unstow all of the packages and then stow them again. This is primarily useful for updating the target directory after files have been added or removed in a package directory.

-t dir

--target=dir

Use dir as the target directory. If not specified, dir defaults to the parent of the current working directory.

-v

--verbose=level

Increase or set the level of noise stow generates as it operates. The default level, 0, is the lowest and will cause stow to print only error messages. The highest noise level is 3, which should produce enough output to irritate anyone.

-V

--version

Print version information and exit.

DESCRIPTION

Stow is a command-line software installation management tool. It creates and deletes links in the target directory tree, for example, /usr/local, which point into the packages with in the stow directory, such as /usr/local/stow/gcc-4.0.3. Each package should be installed in separate directory, with its own bin, lib, man, etc. directory, and then stowed to make it appear that all of the packages are installed in the target directory tree.

By giving each version of each package its own directory, it becomes trivial to roll back to the old version of the package if the new version is in some way lacking. Determining which package installed a file becomes a simple matter of following a symbolic link, likewise for determining which version of a package is installed.

Packages that are configured and built with the autoconf tools are usually easy to fit into this model. The package should usually be configured with the --prefix of the target directory. Once the package is compiled, the prefix should be replaced on the make install line to point to the package directory in the stow tree. For example, if the target directory is /usr/local, one would configure gcc with "./configure --prefix=/usr/local", compile it, and then install as "make prefix=/usr/local/stow/gcc-4.0.3 install". To upgrade to the newly installed package, one would then change directory to /usr/local/stow, unstow the old version ("stow -Dv gcc-3.4.5") and stow the new version ("stow -v gcc-4.0.3").

Some versions of the autoconf tools will complain and refuse to install if the prefix changes, and others install files outside of the prefix's directory tree. In these cases, it is usually possible to use DESTDIR to force the package to outside of the prefix specified at configure time. For example "make DESTDIR=/usr/local/stow/x install" will create the directory tree under /usr/local/stow/x/usr/local. A few shell commands should suffice to move this directory to a suitable location and give it name suitable for stowing.

When unstowing, stow will only ever delete symbolic links and empty directories.

FILES

.stow

The existence of a file named .stow in a directory will prevent stow from examining the contents of that directory.

.placeholder

Stow can be confused by empty directories. If a package needs to include an empty directory then it should be populated with a dummy file. By convention, that file is named .placeholder.

BUGS

Please report bugs bugs to the author.

AUTHORS

The original stow perl script was written by Bob Glickstein, and was inspired by the Carnegie Mellon program Depot. It was then rewritten in C by Ted Phelps <phelps@pobox.com> to improve performance and to make it independent of perl.