(stow.info)Invoking Stow

---

Next: Ignore Lists Prev: Terminology Up: Top

---

Enter node , (file) or (file)node

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=REGEXP'
     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.  Note: Ignore Lists, for more details.

`--defer=REGEXP'
     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 Note: 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=REGEXP'
     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.

`--no-folding'
     This disables any further Note: tree folding or Note: 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.

`--adopt'
     *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 changing.

     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
     ...').

`-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 (Note: 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.  Note: Mixing Operations, for details of when you
     might like to use this feature. This option may be repeated any
     number of times.