3 Invoking Stow
The syntax of the stow command is:
stow [options] [action flag] package ...
Each package is the name of a package (e.g., ‘perl’) in the stow
directory that we wish to install into (or delete from) the target directory.
The default action is to install the given packages, although alternate actions
may be specified by preceding the package name(s) with an action flag.
The following options are supported:
- ‘-d dir’
- Set the stow directory to dir. Defaults to the value of the environment
variable STOW_DIR if set, or the current directory otherwise.
- ‘-t dir’
- Set the target directory to dir instead of the parent of the stow
directory. Defaults to the parent of the stow directory, so it is typical to
execute stow from the directory /usr/local/stow.
- This (repeatable) option lets you suppress acting on files that match the
given perl regular expression. For example, using the options
will cause stow to ignore files ending in .orig or .dist.
Note that the regular expression is anchored to the end of the filename,
because this is what you will want to do most of the time.
Also note that by default Stow automatically ignores a “sensible”
built-in list of files and directories such as CVS, editor
backup files, and so on. See Ignore Lists, for more details.
- This (repeatable) option avoids stowing a file matching the given
regular expression, if that file is already stowed by another package.
This is effectively the opposite of --override.
(N.B. the name --defer was chosen in the sense that the package
currently being stowed is treated with lower precedence than any
already installed package, not in the sense that the operation is
being postponed to be run at a later point in time; do not confuse
this nomenclature with the wording used in Deferred Operation.)
For example, the following options
will cause stow to skip over pre-existing man and info pages.
Equivalently, you could use ‘--defer='man|info'’ since the
argument is just a Perl regex.
Note that the regular expression is anchored to the beginning of the path
relative to the target directory, because this is what you will want to do most
of the time.
- This (repeatable) option forces any file matching the regular expression to be
stowed, even if the file is already stowed to another package. For example,
the following options
will permit stow to overwrite links that point to pre-existing man and info
pages that are owned by stow and would otherwise cause a conflict.
The regular expression is anchored to the beginning of the path relative to
the target directory, because this is what you will want to do most of the time.
This disables any further tree folding or tree refolding.
If a new subdirectory is encountered whilst stowing a new package, the
subdirectory is created within the target, and its contents are
symlinked, rather than just creating a symlink for the directory. If
removal of symlinks whilst unstowing a package causes a subtree to be
foldable (i.e. only containing symlinks to a single package), that
subtree will not be removed and replaced with a symlink.
- Warning! This behaviour is specifically intended to alter the
contents of your stow directory. If you do not want that, this option
is not for you.
When stowing, if a target is encountered which already exists but is a
plain file (and hence not owned by any existing stow package), then
normally Stow will register this as a conflict and refuse to proceed.
This option changes that behaviour so that the file is moved to the
same relative place within the package's installation image within the
stow directory, and then stowing proceeds as before. So effectively,
the file becomes adopted by the stow package, without its contents
This is particularly useful when the stow package is under the control
of a version control system, because it allows files in the target
tree, with potentially different contents to the equivalent versions
in the stow package's installation image, to be adopted into the
package, then compared by running something like ‘git diff ...’
inside the stow package, and finally either kept (e.g. via ‘git
commit ...’) or discarded (‘git checkout HEAD ...’).
- Do not perform any operations that modify the file system; in combination with
-v can be used to merely show what would happen.
- Send verbose output to standard error describing what Stow is
doing. Verbosity levels are 0, 1, 2, and 3; 0 is the default. Using
-v or --verbose increases the verbosity by one; using
‘--verbose=n’ sets it to n.
- Scan the whole target tree when unstowing. By default, only
directories specified in the installation image are scanned
during an unstow operation. Scanning the whole tree can be
prohibitive if your target tree is very large. This option restores
the legacy behaviour; however, the --badlinks option to the
chkstow utility may be a better way of ensuring that your
installation does not have any dangling symlinks (see Target Maintenance).
- Show Stow version number, and exit.
- Show Stow command syntax, and exit.
The following action flags are supported:
- Delete (unstow) the package name(s) that follow this option from the target
directory. This option may be repeated any number of times.
- Restow (first unstow, then stow again) the package names that follow this
option. This is useful for pruning obsolete symlinks from the target tree
after updating the software in a package. This option may be repeated any
number of times.
- explictly stow the package name(s) that follow this option. May be
omitted if you are not using the -D or -R options in the
same invocation. See Mixing Operations, for details of when you
might like to use this feature. This option may be repeated any number