Next: , Previous: Terminology, Up: Top


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
--dir=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
--target=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.
--ignore='<regex>'
This (repeatable) option lets you suppress acting on files that match the given perl regular expression. For example, using the options
          --ignore='*.orig' --ignore='*.dist'

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.

--defer='<regex>'
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

          --defer='man' --defer='info'

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.

--override='<regex>'
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
          --override='man' --override='info'

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.

-n
--no
--simulate
Do not perform any operations that modify the file system; in combination with ‘-v’ can be used to merely show what would happen.
-v
--verbose[=n]
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.
-p
--compat
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).
-V
--version
Show Stow version number, and exit.
-h
--help
Show Stow command syntax, and exit.

The following action flags are supported:

-D
--delete
Delete (unstow) the package name(s) that follow this option from the target directory. This option may be repeated any number of times.
-R
--restow
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.
-S
--stow
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 of times.