1stow(8)               User Contributed Perl Documentation              stow(8)
2
3
4

NAME

6       stow - manage farms of symbolic links
7

SYNOPSIS

9       stow [ options ] package ...
10

DESCRIPTION

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
16       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
20       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
29       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
36       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
41       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
50       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

TERMINOLOGY

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
59       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
64       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
70       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
77       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
83       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
89       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

OPTIONS

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
105       -n
106       --no
107           Do not perform any operations that modify the filesystem; merely
108           show what would happen.
109
110       -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
116       -t DIR
117       --target=DIR
118           Set the target directory to "DIR" instead of the parent of the stow
119           directory.
120
121       -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
128       -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
135       -D
136       --delete
137           Unstow the packages that follow this option from the target
138           directory rather than installing them.
139
140       -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
146       --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
151           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
160       --no-folding
161           Disable folding of newly stowed directories when stowing, and
162           refolding of newly foldable directories when unstowing.
163
164       --ignore=REGEX
165           Ignore files ending in this Perl regex.
166
167       --defer=REGEX
168           Don't stow files beginning with this Perl regex if the file is
169           already stowed to another package.
170
171       --override=REGEX
172           Force stowing files beginning with this Perl regex if the file is
173           already stowed to another package.
174
175       --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
184           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
190       -V
191       --version
192           Show Stow version number, and exit.
193
194       -h
195       --help
196           Show Stow command syntax, and exit.
197

INSTALLING PACKAGES

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
206       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
218       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
223       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
236       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
253       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
257   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
263       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

DELETING PACKAGES

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
274       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

RESOURCE FILES

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
291       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
298       Environment variables and the tilde character (~) will be expanded for
299       options that take a file path.
300
301       The options -D, -R, -S, and any packages listed in the resource file
302       are ignored.
303
304       See the info manual for more information on how stow handles resource
305       file.
306

SEE ALSO

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
312           info stow
313
314       should give you access to the complete manual.
315

BUGS

317       Please report bugs in Stow using the Debian bug tracking system.
318
319       Currently known bugs include:
320
321       ·   The empty-directory problem.
322
323           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
334       ·   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

AUTHOR

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
360       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
364       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
371       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.
375
376
377
378perl v5.26.1                      2019-07-28                           stow(8)
Impressum