1stow(8) User Contributed Perl Documentation stow(8)
2
6 stow - manage farms of symbolic links
7
9 stow [ options ] package ...
10
12 This manual page describes GNU Stow 2.3.1. This is not the definitive
13 documentation for Stow; for that, see the accompanying info manual,
14 e.g. by typing "info stow".
15 Stow is a symlink farm manager which takes distinct sets of software
17 and/or data located in separate directories on the filesystem, and
18 makes them all appear to be installed in a single directory tree.
19 Originally Stow was born to address the need to administer, upgrade,
21 install, and remove files in independent software packages without
22 confusing them with other files sharing the same file system space.
23 For instance, many years ago it used to be common to compile programs
24 such as Perl and Emacs from source. By using Stow, /usr/local/bin
25 could contain symlinks to files within /usr/local/stow/emacs/bin,
26 /usr/local/stow/perl/bin etc., and likewise recursively for any other
27 subdirectories such as .../share, .../man, and so on.
28 While this is useful for keeping track of system-wide and per-user
30 installations of software built from source, in more recent times
31 software packages are often managed by more sophisticated package
32 management software such as rpm, dpkg, and Nix / GNU Guix, or language-
33 native package managers such as Ruby's gem, Python's pip, Javascript's
34 npm, and so on.
35 However Stow is still used not only for software package management,
37 but also for other purposes, such as facilitating a more controlled
38 approach to management of configuration files in the user's home
39 directory, especially when coupled with version control systems.
40 Stow was inspired by Carnegie Mellon's Depot program, but is
42 substantially simpler and safer. Whereas Depot required database files
43 to keep things in sync, Stow stores no extra state between runs, so
44 there's no danger (as there was in Depot) of mangling directories when
45 file hierarchies don't match the database. Also unlike Depot, Stow will
46 never delete any files, directories, or links that appear in a Stow
47 directory (e.g., /usr/local/stow/emacs), so it's always possible to
48 rebuild the target tree (e.g., /usr/local).
49 Stow is implemented as a combination of a Perl script providing a CLI
51 interface, and a backend Perl module which does most of the work.
52
54 A "package" is a related collection of files and directories that you
55 wish to administer as a unit -- e.g., Perl or Emacs -- and that needs
56 to be installed in a particular directory structure -- e.g., with bin,
57 lib, and man subdirectories.
58 A "target directory" is the root of a tree in which one or more
60 packages wish to appear to be installed. A common, but by no means the
61 only such location is /usr/local. The examples in this manual page
62 will use /usr/local as the target directory.
63 A "stow directory" is the root of a tree containing separate packages
65 in private subtrees. When Stow runs, it uses the current directory as
66 the default stow directory. The examples in this manual page will use
67 /usr/local/stow as the stow directory, so that individual packages will
68 be, for example, /usr/local/stow/perl and /usr/local/stow/emacs.
69 An "installation image" is the layout of files and directories required
71 by a package, relative to the target directory. Thus, the installation
72 image for Perl includes: a bin directory containing perl and a2p (among
73 others); an info directory containing Texinfo documentation; a lib/perl
74 directory containing Perl libraries; and a man/man1 directory
75 containing man pages.
76 A "package directory" is the root of a tree containing the installation
78 image for a particular package. Each package directory must reside in a
79 stow directory -- e.g., the package directory /usr/local/stow/perl must
80 reside in the stow directory /usr/local/stow. The "name" of a package
81 is the name of its directory within the stow directory -- e.g., perl.
82 Thus, the Perl executable might reside in
84 /usr/local/stow/perl/bin/perl, where /usr/local is the target
85 directory, /usr/local/stow is the stow directory, /usr/local/stow/perl
86 is the package directory, and bin/perl within is part of the
87 installation image.
88 A "symlink" is a symbolic link. A symlink can be "relative" or
90 "absolute". An absolute symlink names a full path; that is, one
91 starting from /. A relative symlink names a relative path; that is,
92 one not starting from /. The target of a relative symlink is computed
93 starting from the symlink's own directory. Stow only creates relative
94 symlinks.
95
97 The stow directory is assumed to be the value of the "STOW_DIR"
98 environment variable or if unset the current directory, and the target
99 directory is assumed to be the parent of the current directory (so it
100 is typical to execute stow from the directory /usr/local/stow). Each
101 package given on the command line is the name of a package in the stow
102 directory (e.g., perl). By default, they are installed into the target
103 directory (but they can be deleted instead using "-D").
104 -n
106 --no
107 Do not perform any operations that modify the filesystem; merely
108 show what would happen.
109 -d DIR
111 --dir=DIR
112 Set the stow directory to "DIR" instead of the current directory.
113 This also has the effect of making the default target directory be
114 the parent of "DIR".
115 -t DIR
117 --target=DIR
118 Set the target directory to "DIR" instead of the parent of the stow
119 directory.
120 -v
122 --verbose[=N]
123 Send verbose output to standard error describing what Stow is
124 doing. Verbosity levels are from 0 to 5; 0 is the default. Using
125 "-v" or "--verbose" increases the verbosity by one; using
126 `--verbose=N' sets it to N.
127 -S
129 --stow
130 Stow the packages that follow this option into the target
131 directory. This is the default action and so can be omitted if you
132 are only stowing packages rather than performing a mixture of
133 stow/delete/restow actions.
134 -D
136 --delete
137 Unstow the packages that follow this option from the target
138 directory rather than installing them.
139 -R
141 --restow
142 Restow packages (first unstow, then stow again). This is useful for
143 pruning obsolete symlinks from the target tree after updating the
144 software in a package.
145 --adopt
147 Warning! This behaviour is specifically intended to alter the
148 contents of your stow directory. If you do not want that, this
149 option is not for you.
150 When stowing, if a target is encountered which already exists but
152 is a plain file (and hence not owned by any existing stow package),
153 then normally Stow will register this as a conflict and refuse to
154 proceed. This option changes that behaviour so that the file is
155 moved to the same relative place within the package's installation
156 image within the stow directory, and then stowing proceeds as
157 before. So effectively, the file becomes adopted by the stow
158 package, without its contents changing.
159 --no-folding
161 Disable folding of newly stowed directories when stowing, and
162 refolding of newly foldable directories when unstowing.
163 --ignore=REGEX
165 Ignore files ending in this Perl regex.
166 --defer=REGEX
168 Don't stow files beginning with this Perl regex if the file is
169 already stowed to another package.
170 --override=REGEX
172 Force stowing files beginning with this Perl regex if the file is
173 already stowed to another package.
174 --dotfiles
176 Enable special handling for "dotfiles" (files or folders whose name
177 begins with a period) in the package directory. If this option is
178 enabled, Stow will add a preprocessing step for each file or folder
179 whose name begins with "dot-", and replace the "dot-" prefix in the
180 name by a period (.). This is useful when Stow is used to manage
181 collections of dotfiles, to avoid having a package directory full
182 of hidden files.
183 For example, suppose we have a package containing two files,
185 stow/dot-bashrc and stow/dot-emacs.d/init.el. With this option,
186 Stow will create symlinks from .bashrc to stow/dot-bashrc and from
187 .emacs.d/init.el to stow/dot-emacs.d/init.el. Any other files,
188 whose name does not begin with "dot-", will be processed as usual.
189 -V
191 --version
192 Show Stow version number, and exit.
193 -h
195 --help
196 Show Stow command syntax, and exit.
197
199 The default action of Stow is to install a package. This means creating
200 symlinks in the target tree that point into the package tree. Stow
201 attempts to do this with as few symlinks as possible; in other words,
202 if Stow can create a single symlink that points to an entire subtree
203 within the package tree, it will choose to do that rather than create a
204 directory in the target tree and populate it with symlinks.
205 For example, suppose that no packages have yet been installed in
207 /usr/local; it's completely empty (except for the stow subdirectory, of
208 course). Now suppose the Perl package is installed. Recall that it
209 includes the following directories in its installation image: bin;
210 info; lib/perl; man/man1. Rather than creating the directory
211 /usr/local/bin and populating it with symlinks to ../stow/perl/bin/perl
212 and ../stow/perl/bin/a2p (and so on), Stow will create a single
213 symlink, /usr/local/bin, which points to stow/perl/bin. In this way,
214 it still works to refer to /usr/local/bin/perl and /usr/local/bin/a2p,
215 and fewer symlinks have been created. This is called "tree folding",
216 since an entire subtree is "folded" into a single symlink.
217 To complete this example, Stow will also create the symlink
219 /usr/local/info pointing to stow/perl/info; the symlink /usr/local/lib
220 pointing to stow/perl/lib; and the symlink /usr/local/man pointing to
221 stow/perl/man.
222 Now suppose that instead of installing the Perl package into an empty
224 target tree, the target tree is not empty to begin with. Instead, it
225 contains several files and directories installed under a different
226 system-administration philosophy. In particular, /usr/local/bin already
227 exists and is a directory, as are /usr/local/lib and
228 /usr/local/man/man1. In this case, Stow will descend into
229 /usr/local/bin and create symlinks to ../stow/perl/bin/perl and
230 ../stow/perl/bin/a2p (etc.), and it will descend into /usr/local/lib
231 and create the tree-folding symlink perl pointing to
232 ../stow/perl/lib/perl, and so on. As a rule, Stow only descends as far
233 as necessary into the target tree when it can create a tree-folding
234 symlink.
235 The time often comes when a tree-folding symlink has to be undone
237 because another package uses one or more of the folded subdirectories
238 in its installation image. This operation is called "splitting open" a
239 folded tree. It involves removing the original symlink from the target
240 tree, creating a true directory in its place, and then populating the
241 new directory with symlinks to the newly-installed package and to the
242 old package that used the old symlink. For example, suppose that after
243 installing Perl into an empty /usr/local, we wish to install Emacs.
244 Emacs's installation image includes a bin directory containing the
245 emacs and etags executables, among others. Stow must make these files
246 appear to be installed in /usr/local/bin, but presently /usr/local/bin
247 is a symlink to stow/perl/bin. Stow therefore takes the following
248 steps: the symlink /usr/local/bin is deleted; the directory
249 /usr/local/bin is created; links are made from /usr/local/bin to
250 ../stow/emacs/bin/emacs and ../stow/emacs/bin/etags; and links are made
251 from /usr/local/bin to ../stow/perl/bin/perl and ../stow/perl/bin/a2p.
252 When splitting open a folded tree, Stow makes sure that the symlink it
254 is about to remove points inside a valid package in the current stow
255 directory.
256 Stow will never delete anything that it doesn't own.
258 Stow "owns" everything living in the target tree that points into a
259 package in the stow directory. Anything Stow owns, it can recompute if
260 lost. Note that by this definition, Stow doesn't "own" anything in the
261 stow directory or in any of the packages.
262 If Stow needs to create a directory or a symlink in the target tree and
264 it cannot because that name is already in use and is not owned by Stow,
265 then a conflict has arisen. See the "Conflicts" section in the info
266 manual.
267
269 When the "-D" option is given, the action of Stow is to delete a
270 package from the target tree. Note that Stow will not delete anything
271 it doesn't "own". Deleting a package does not mean removing it from the
272 stow directory or discarding the package tree.
273 To delete a package, Stow recursively scans the target tree, skipping
275 over the stow directory (since that is usually a subdirectory of the
276 target tree) and any other stow directories it encounters (see
277 "Multiple stow directories" in the info manual). Any symlink it finds
278 that points into the package being deleted is removed. Any directory
279 that contained only symlinks to the package being deleted is removed.
280 Any directory that, after removing symlinks and empty subdirectories,
281 contains only symlinks to a single other package, is considered to be a
282 previously "folded" tree that was "split open." Stow will re-fold the
283 tree by removing the symlinks to the surviving package, removing the
284 directory, then linking the directory back to the surviving package.
285
287 Stow searches for default command line options at .stowrc (current
288 directory) and ~/.stowrc (home directory) in that order. If both
289 locations are present, the files are effectively appended together.
290 The effect of options in the resource file is similar to simply
292 prepending the options to the command line. For options that provide a
293 single value, such as --target or --dir, the command line option will
294 overwrite any options in the resource file. For options that can be
295 given more than once, --ignore for example, command line options and
296 resource options are appended together.
297 Environment variables and the tilde character (~) will be expanded for
299 options that take a file path.
300 The options -D, -R, -S, and any packages listed in the resource file
302 are ignored.
303 See the info manual for more information on how stow handles resource
305 file.
306
308 The full documentation for stow is maintained as a Texinfo manual. If
309 the info and stow programs are properly installed at your site, the
310 command
311 info stow
313 should give you access to the complete manual.
315
317 Please report bugs in Stow using the Debian bug tracking system.
318 Currently known bugs include:
320 · The empty-directory problem.
322 If package foo includes an empty directory -- say, foo/bar -- then
324 if no other package has a bar subdirectory, everything's fine. If
325 another stowed package quux, has a bar subdirectory, then when
326 stowing, targetdir/bar will be "split open" and the contents of
327 quux/bar will be individually stowed. So far, so good. But when
328 unstowing quux, targetdir/bar will be removed, even though foo/bar
329 needs it to remain. A workaround for this problem is to create a
330 file in foo/bar as a placeholder. If you name that file
331 .placeholder, it will be easy to find and remove such files when
332 this bug is fixed.
333 · When using multiple stow directories (see "Multiple stow
335 directories" in the info manual), Stow fails to "split open" tree-
336 folding symlinks (see "Installing packages" in the info manual)
337 that point into a stow directory which is not the one in use by the
338 current Stow command. Before failing, it should search the target
339 of the link to see whether any element of the path contains a .stow
340 file. If it finds one, it can "learn" about the cooperating stow
341 directory to short-circuit the .stow search the next time it
342 encounters a tree-folding symlink.
343
345 This man page was originally constructed by Charles Briscoe-Smith from
346 parts of Stow's info manual, and then converted to POD format by Adam
347 Spiers. The info manual contains the following notice, which, as it
348 says, applies to this manual page, too. The text of the section
349 entitled "GNU General Public License" can be found in the file
350 /usr/share/common-licenses/GPL on any Debian GNU/Linux system. If you
351 don't have access to a Debian system, or the GPL is not there, write to
352 the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
353 MA, 02111-1307, USA.
354
356 Copyright (C) 1993, 1994, 1995, 1996 by Bob Glickstein
357 <bobg+stow@zanshin.com>; 2000, 2001 by Guillaume Morin; 2007 by Kahlil
358 Hodgson; 2011 by Adam Spiers; and others.
359 Permission is granted to make and distribute verbatim copies of this
361 manual provided the copyright notice and this permission notice are
362 preserved on all copies.
363 Permission is granted to copy and distribute modified versions of this
365 manual under the conditions for verbatim copying, provided also that
366 the section entitled "GNU General Public License" is included with the
367 modified manual, and provided that the entire resulting derived work is
368 distributed under the terms of a permission notice identical to this
369 one.
370 Permission is granted to copy and distribute translations of this
372 manual into another language, under the above conditions for modified
373 versions, except that this permission notice may be stated in a
374 translation approved by the Free Software Foundation.
375perl v5.26.1 2019-07-28 stow(8)