291 lines
14 KiB
HTML
291 lines
14 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<!-- This manual describes GNU Stow version 2.3.2-fixbug56727
|
|
(2 November 2023), a program for managing farms of symbolic links.
|
|
|
|
Software and documentation is copyrighted by the following:
|
|
|
|
© 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>
|
|
|
|
|
|
© 2000, 2001 Guillaume Morin <gmorin@gnu.org>
|
|
|
|
|
|
© 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>
|
|
|
|
|
|
© 2011 Adam Spiers <stow@adamspiers.org>
|
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
|
manual provided the copyright notice and this permission notice are
|
|
preserved on all copies.
|
|
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided also that the
|
|
section entitled "GNU General Public License" is included with the
|
|
modified manual, and provided that the entire resulting derived work is
|
|
distributed under the terms of a permission notice identical to this
|
|
one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that this permission notice may be stated in a translation
|
|
approved by the Free Software Foundation. -->
|
|
<title>Invoking Stow (Stow)</title>
|
|
|
|
<meta name="description" content="Invoking Stow (Stow)">
|
|
<meta name="keywords" content="Invoking Stow (Stow)">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content="makeinfo">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
|
|
<link href="index.html" rel="start" title="Top">
|
|
<link href="Index.html" rel="index" title="Index">
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
|
<link href="index.html" rel="up" title="Top">
|
|
<link href="Ignore-Lists.html" rel="next" title="Ignore Lists">
|
|
<link href="Terminology.html" rel="prev" title="Terminology">
|
|
<style type="text/css">
|
|
<!--
|
|
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
|
|
div.example {margin-left: 3.2em}
|
|
span:hover a.copiable-link {visibility: visible}
|
|
-->
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en">
|
|
<div class="chapter-level-extent" id="Invoking-Stow">
|
|
<div class="nav-panel">
|
|
<p>
|
|
Next: <a href="Ignore-Lists.html" accesskey="n" rel="next">Ignore Lists</a>, Previous: <a href="Terminology.html" accesskey="p" rel="prev">Terminology</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<hr>
|
|
<h2 class="chapter" id="Invoking-Stow-1"><span>3 Invoking Stow<a class="copiable-link" href="#Invoking-Stow-1"> ¶</a></span></h2>
|
|
|
|
<p>The syntax of the <code class="command">stow</code> command is:
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example-preformatted">stow [<var class="var">options</var>] [<var class="var">action flag</var>] <var class="var">package ...</var>
|
|
</pre></div>
|
|
|
|
<p>Each <var class="var">package</var> is the name of a package (e.g., ‘<samp class="samp">perl</samp>’) 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 <var class="var">action flag</var>.
|
|
</p>
|
|
<p>The following options are supported:
|
|
</p>
|
|
<dl class="table">
|
|
<dt>‘<samp class="samp">-d <var class="var">dir</var></samp>’</dt>
|
|
<dt>‘<samp class="samp">--dir=<var class="var">dir</var></samp>’</dt>
|
|
<dd><p>Set the stow directory to <var class="var">dir</var>. Defaults to the value of the environment
|
|
variable <code class="env">STOW_DIR</code> if set, or the current directory otherwise.
|
|
</p>
|
|
</dd>
|
|
<dt>‘<samp class="samp">-t <var class="var">dir</var></samp>’</dt>
|
|
<dt>‘<samp class="samp">--target=<var class="var">dir</var></samp>’</dt>
|
|
<dd><p>Set the target directory to <var class="var">dir</var> instead of the parent of the stow
|
|
directory. Defaults to the parent of the stow directory, so it is typical to
|
|
execute <code class="command">stow</code> from the directory <samp class="file">/usr/local/stow</samp>.
|
|
</p>
|
|
</dd>
|
|
<dt>‘<samp class="samp">--ignore=<var class="var">regexp</var></samp>’</dt>
|
|
<dd><p>This (repeatable) option lets you suppress acting on files that match the
|
|
given Perl regular expression. For example, using the options
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example-preformatted">--ignore='.*\.orig' --ignore='.*\.dist'
|
|
</pre></div>
|
|
|
|
<p>will cause stow to ignore files ending in <samp class="file">.orig</samp> or <samp class="file">.dist</samp>.
|
|
</p>
|
|
<p>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.
|
|
</p>
|
|
<p>Also note that by default Stow automatically ignores a “sensible”
|
|
built-in list of files and directories such as <samp class="file">CVS</samp>, editor
|
|
backup files, and so on. See <a class="xref" href="Ignore-Lists.html">Ignore Lists</a>, for more details.
|
|
</p>
|
|
</dd>
|
|
<dt>‘<samp class="samp">--defer=<var class="var">regexp</var></samp>’</dt>
|
|
<dd><p>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 <samp class="option">--override</samp>.
|
|
</p>
|
|
<p>(N.B. the name <samp class="option">--defer</samp> 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 <a class="ref" href="Conflicts.html#Deferred-Operation">Deferred Operation</a>.)
|
|
</p>
|
|
<p>For example, the following options
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example-preformatted">--defer=man --defer=info
|
|
</pre></div>
|
|
|
|
<p>will cause stow to skip over pre-existing man and info pages.
|
|
</p>
|
|
<p>Equivalently, you could use ‘<samp class="samp">--defer='man|info'</samp>’ since the
|
|
argument is just a Perl regular expression.
|
|
</p>
|
|
<p>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.
|
|
</p>
|
|
</dd>
|
|
<dt>‘<samp class="samp">--override=<var class="var">regexp</var></samp>’</dt>
|
|
<dd><p>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
|
|
</p>
|
|
<div class="example">
|
|
<pre class="example-preformatted">--override=man --override=info
|
|
</pre></div>
|
|
|
|
<p>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.
|
|
</p>
|
|
<p>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.
|
|
</p>
|
|
</dd>
|
|
<dt><a id="index-dotfiles"></a><span>‘<samp class="samp">--dotfiles</samp>’<a class="copiable-link" href="#index-dotfiles"> ¶</a></span></dt>
|
|
<dd>
|
|
<p>Enable special handling for <em class="emph">dotfiles</em> (files or folders whose
|
|
name begins with a period) in the package directory. If this option is
|
|
enabled, Stow will add a preprocessing step for each file or folder
|
|
whose name begins with ‘<samp class="samp">dot-</samp>’, and replace the ‘<samp class="samp">dot-</samp>’ prefix
|
|
in the name by a period ‘<samp class="samp">.</samp>’. This is useful when Stow is used to
|
|
manage collections of dotfiles, to avoid having a package directory
|
|
full of hidden files.
|
|
</p>
|
|
<p>For example, suppose we have a package containing two files,
|
|
<samp class="file">stow/dot-bashrc</samp> and <samp class="file">stow/dot-emacs.d/init.el</samp>. With this
|
|
option, Stow will create symlinks from <samp class="file">.bashrc</samp> to
|
|
<samp class="file">stow/dot-bashrc</samp> and from <samp class="file">.emacs.d/init.el</samp> to
|
|
<samp class="file">stow/dot-emacs.d/init.el</samp>. Any other files, whose name does not
|
|
begin with ‘<samp class="samp">dot-</samp>’, will be processed as usual.
|
|
</p>
|
|
</dd>
|
|
<dt>‘<samp class="samp">--no-folding</samp>’</dt>
|
|
<dd>
|
|
<p>This disables any further tree folding (see <a class="pxref" href="Installing-Packages.html#tree-folding">tree folding</a>) or
|
|
refolding (see <a class="pxref" href="Deleting-Packages.html#tree-refolding">tree refolding</a>). 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.
|
|
</p>
|
|
</dd>
|
|
<dt><a id="index-adopting-existing-files"></a><span>‘<samp class="samp">--adopt</samp>’<a class="copiable-link" href="#index-adopting-existing-files"> ¶</a></span></dt>
|
|
<dd><p><strong class="strong">Warning!</strong> 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.
|
|
</p>
|
|
<p>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.
|
|
</p>
|
|
<p>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 ‘<samp class="samp">git diff ...</samp>’
|
|
inside the stow package, and finally either kept (e.g. via ‘<samp class="samp">git
|
|
commit ...</samp>’) or discarded (‘<samp class="samp">git checkout HEAD ...</samp>’).
|
|
</p>
|
|
</dd>
|
|
<dt><a class="index-entry-id" id="index-simulated-run"></a>
|
|
<a id="index-dry-run"></a><span>‘<samp class="samp">-n</samp>’<a class="copiable-link" href="#index-dry-run"> ¶</a></span></dt>
|
|
<dt>‘<samp class="samp">--no</samp>’</dt>
|
|
<dt>‘<samp class="samp">--simulate</samp>’</dt>
|
|
<dd><p>Do not perform any operations that modify the file system; in combination with
|
|
<samp class="option">-v</samp> can be used to merely show what would happen.
|
|
</p>
|
|
</dd>
|
|
<dt><a id="index-verbosity-levels"></a><span>‘<samp class="samp">-v</samp>’<a class="copiable-link" href="#index-verbosity-levels"> ¶</a></span></dt>
|
|
<dt>‘<samp class="samp">--verbose[=<var class="var">n</var>]</samp>’</dt>
|
|
<dd><p>Send verbose output to standard error describing what Stow is
|
|
doing. Verbosity levels are from 0 to 5; 0 is the default. Using
|
|
<samp class="option">-v</samp> or <samp class="option">--verbose</samp> increases the verbosity by one; using
|
|
‘<samp class="samp">--verbose=<var class="var">n</var></samp>’ sets it to <var class="var">n</var>.
|
|
</p>
|
|
</dd>
|
|
<dt>‘<samp class="samp">-p</samp>’</dt>
|
|
<dt>‘<samp class="samp">--compat</samp>’</dt>
|
|
<dd><p>Scan the whole target tree when unstowing. By default, only
|
|
directories specified in the <em class="dfn">installation image</em> 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 <samp class="option">--badlinks</samp> option to the
|
|
<code class="command">chkstow</code> utility may be a better way of ensuring that your
|
|
installation does not have any dangling symlinks (see <a class="pxref" href="Target-Maintenance.html">Target Maintenance</a>).
|
|
</p>
|
|
</dd>
|
|
<dt>‘<samp class="samp">-V</samp>’</dt>
|
|
<dt>‘<samp class="samp">--version</samp>’</dt>
|
|
<dd><p>Show Stow version number, and exit.
|
|
</p>
|
|
</dd>
|
|
<dt>‘<samp class="samp">-h</samp>’</dt>
|
|
<dt>‘<samp class="samp">--help</samp>’</dt>
|
|
<dd><p>Show Stow command syntax, and exit.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
<p>The following <var class="var">action flags</var> are supported:
|
|
</p>
|
|
<dl class="table">
|
|
<dt>‘<samp class="samp">-D</samp>’</dt>
|
|
<dt>‘<samp class="samp">--delete</samp>’</dt>
|
|
<dd><p>Delete (unstow) the package name(s) that follow this option from the <em class="dfn">target
|
|
directory</em>. This option may be repeated any number of times.
|
|
</p>
|
|
</dd>
|
|
<dt>‘<samp class="samp">-R</samp>’</dt>
|
|
<dt>‘<samp class="samp">--restow</samp>’</dt>
|
|
<dd><p>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.
|
|
</p>
|
|
</dd>
|
|
<dt>‘<samp class="samp">-S</samp>’</dt>
|
|
<dt>‘<samp class="samp">--stow</samp>’</dt>
|
|
<dd><p>explictly stow the package name(s) that follow this option. May be
|
|
omitted if you are not using the <samp class="option">-D</samp> or <samp class="option">-R</samp> options in the
|
|
same invocation. See <a class="xref" href="Mixing-Operations.html">Mixing Operations</a>, for details of when you
|
|
might like to use this feature. This option may be repeated any number
|
|
of times.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
|
|
</div>
|
|
<hr>
|
|
<div class="nav-panel">
|
|
<p>
|
|
Next: <a href="Ignore-Lists.html">Ignore Lists</a>, Previous: <a href="Terminology.html">Terminology</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|