1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, 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.4.1
(8 September 2024), 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">
<!--
div.example {margin-left: 3.2em}
-->
</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">3 Invoking Stow</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>
<a class="index-entry-id" id="index-dotfiles"></a>
</dd>
<dt>‘<samp class="samp">--dotfiles</samp>’</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>
<p>Note that when this option is enabled, any package file or directory
prefixed with ‘<samp class="samp">dot-</samp>’ is assumed to be named deliberately to be
stowed with a ‘<samp class="samp">.</samp>’ prefix, and therefore will only be ignored if
there is an entry in the ignore list (See <a class="xref" href="Ignore-Lists.html">Ignore Lists</a>) which matches
this prefix. So for example, by default <samp class="file">dot-gitignore</samp> would not
be ignored even though ‘<samp class="samp">\.gitignore</samp>’ is in the default ignore list.
</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>
<a class="index-entry-id" id="index-adopting-existing-files"></a>
</dd>
<dt>‘<samp class="samp">--adopt</samp>’</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>
<a class="index-entry-id" id="index-dry-run"></a>
<a class="index-entry-id" id="index-simulated-run"></a>
</dd>
<dt>‘<samp class="samp">-n</samp>’</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>
<a class="index-entry-id" id="index-verbosity-levels"></a>
</dd>
<dt>‘<samp class="samp">-v</samp>’</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. Previously Stow scanned the whole tree, which can be
prohibitive if your target tree is very large, but on the other hand has
the advantage of unstowing previously stowed links which are no longer
present in the installation image and therefore orphaned. 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>
|
