dot/stow
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Rebuild based on upstream Stow 2.4.0

Browse source
This commit is contained in:
Danielle McLean 2024-06-03 13:08:10 +10:00
parent be6413057e
commit 91c35521c9
Signed by: 00dani
GPG key ID: 6854781A0488421C
39 changed files with 1968 additions and 1231 deletions
Download patch file Download diff file Expand all files Collapse all files

242
dot-local/share/info/stow.info
View file

@ -1,7 +1,7 @@
This is stow.info, produced by makeinfo version 7.1 from stow.texi.
This manual describes GNU Stow version 2.3.2-fixbug56727 (2 November
2023), a program for managing farms of symbolic links.
This manual describes GNU Stow version 2.4.0 (3 June 2024), a program
for managing farms of symbolic links.
Software and documentation is copyrighted by the following:
@ -36,10 +36,10 @@ File: stow.info, Node: Top, Next: Introduction, Up: (dir)
Stow
****
This manual describes GNU Stow 2.3.2-fixbug56727 (2 November 2023), a
symlink farm manager which takes distinct sets of software and/or data
located in separate directories on the filesystem, and makes them appear
to be installed in a single directory tree.
This manual describes GNU Stow 2.4.0 (3 June 2024), a symlink farm
manager which takes distinct sets of software and/or data located in
separate directories on the filesystem, and makes them appear to be
installed in a single directory tree.
* Menu:
@ -54,7 +54,7 @@ to be installed in a single directory tree.
* Multiple Stow Directories:: Further segregating software.
* Target Maintenance:: Cleaning up mistakes.
* Resource Files:: Setting default command line options.
* Compile-time vs Install-time:: Faking out 'make install'.
* Compile-time vs. Install-time:: Faking out 'make install'.
* Bootstrapping:: When stow and perl are not yet stowed.
* Reporting Bugs:: How, what, where, and when to report.
* Known Bugs:: Don't report any of these.
@ -174,9 +174,12 @@ be installed in a particular directory structure -- e.g., with ‘bin’,
‘lib’, and ‘man’ subdirectories.
A “target directory” is the root of a tree in which one or more
packages wish to _appear_ to be installed. A common, but by no means
the only such location is ‘/usr/local’. The examples in this manual
will use ‘/usr/local’ as the target directory.
packages wish to _appear_ to be installed. ‘/usr/local’ is a common
choice for this, but by no means the only such location. Another common
choice is ‘~’ (i.e. the user's ‘$HOME’ directory) in the case where Stow
is being used to manage the user's configuration ("dotfiles") and other
files in their ‘$HOME’. The examples in this manual will use
‘/usr/local’ as the target directory.
A “stow directory” is the root of a tree containing separate packages
in private subtrees. When Stow runs, it uses the current directory as
@ -192,6 +195,10 @@ installation image for Perl includes: a ‘bin’ directory containing
documentation; a ‘lib/perl’ directory containing Perl libraries; and a
‘man/man1’ directory containing man pages.
Note: This is a _pre-_installation image which exists even before
Stow has installed any symlinks into the target directory which
point to it.
A “package directory” is the root of a tree containing the
installation image for a particular package. Each package directory
must reside in a stow directory -- e.g., the package directory
@ -205,12 +212,46 @@ directory, ‘/usr/local/stow’ is the stow directory,
‘/usr/local/stow/perl’ is the package directory, and ‘bin/perl’ within
is part of the installation image.
A “symlink” is a symbolic link. A symlink can be “relative” or
“absolute”. An absolute symlink names a full path; that is, one
starting from ‘/’. A relative symlink names a relative path; that is,
one not starting from ‘/’. The target of a relative symlink is computed
starting from the symlink's own directory. Stow only creates relative
symlinks.
A “symlink” is a symbolic link, i.e. an entry on the filesystem whose
path is sometimes called the “symlink source”, which points to another
location on the filesystem called the “symlink destination”. There is
no guarantee that the destination actually exists.
In general, symlinks can be “relative” or “absolute”. A symlink is
absolute when the destination names a full path; that is, one starting
from ‘/’. A symlink is relative when the destination names a relative
path; that is, one not starting from ‘/’. The destination of a relative
symlink is computed starting from the symlink's own directory, i.e. the
directory containing the symlink source.
Note: Stow only creates symlinks within the target directory which
point to locations _outside_ the target directory and inside the
stow directory.
Consequently, we avoid referring to symlink destinations as symlink
_targets_, since this would result in the word "target" having two
different meanings:
1. the target directory, i.e. the directory into which Stow
targets installation, where symlinks are managed by Stow, and
2. the destinations of those symlinks.
If we did not avoid the second meaning of "target", then it would
lead to confusing language, such as describing Stow as installing
symlinks into the target directory which point to targets _outside_
the target directory.
Similarly, the word "source" can have two different meanings in
this context:
1. the installation image, or some of its contents, and
2. the location of symlinks (the "source" of the link, vs. its
destination).
Therefore it should also be avoided, or at least care taken to
ensure that the meaning is not ambiguous.

File: stow.info, Node: Invoking Stow, Next: Ignore Lists, Prev: Terminology, Up: Top
@ -324,7 +365,7 @@ The following options are supported:
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
(i.e. only containing symlinks to a single package), that subtree
will not be removed and replaced with a symlink.
‘--adopt’
@ -366,12 +407,14 @@ The following options are supported:
‘--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::).
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 ‘--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’
@ -475,6 +518,7 @@ list files:
\.git
\.gitignore
\.gitmodules
.+~ # emacs backup files
\#.*\# # emacs autosave files
@ -755,7 +799,7 @@ invocation.
invocations of stow, because redundant folding/unfolding operations can
be factored out. In addition, all the operations are calculated and
merged before being executed (*note Deferred Operation::), so the amount
of of time in which GNU Emacs is unavailable is minimised.
of time in which GNU Emacs is unavailable is minimised.
You can mix and match any number of actions, for example,
@ -825,7 +869,7 @@ The following options are supported:
target directory.

File: stow.info, Node: Resource Files, Next: Compile-time vs Install-time, Prev: Target Maintenance, Up: Top
File: stow.info, Node: Resource Files, Next: Compile-time vs. Install-time, Prev: Target Maintenance, Up: Top
11 Resource Files
*****************
@ -884,10 +928,10 @@ escape the ‘$’ or ‘~’ with a backslash.
is also true of any package names given in the resource file.

File: stow.info, Node: Compile-time vs Install-time, Next: Bootstrapping, Prev: Resource Files, Up: Top
File: stow.info, Node: Compile-time vs. Install-time, Next: Bootstrapping, Prev: Resource Files, Up: Top
12 Compile-time vs Install-time
*******************************
12 Compile-time vs. Install-time
********************************
Software whose installation is managed with Stow needs to be installed
in one place (the package directory, e.g. ‘/usr/local/stow/perl’) but
@ -962,7 +1006,7 @@ following sections.
* Perl and Perl 5 Modules::

File: stow.info, Node: GNU Emacs, Next: Other FSF Software, Prev: Compile-time vs Install-time, Up: Compile-time vs Install-time
File: stow.info, Node: GNU Emacs, Next: Other FSF Software, Prev: Compile-time vs. Install-time, Up: Compile-time vs. Install-time
12.2 GNU Emacs
==============
@ -993,7 +1037,7 @@ around this problem is:
(1) As I write this, the current version of Emacs is 19.31.

File: stow.info, Node: Other FSF Software, Next: Cygnus Software, Prev: GNU Emacs, Up: Compile-time vs Install-time
File: stow.info, Node: Other FSF Software, Next: Cygnus Software, Prev: GNU Emacs, Up: Compile-time vs. Install-time
12.3 Other FSF Software
=======================
@ -1013,7 +1057,7 @@ and ‘make install’ steps to work correctly without needing to "fool" the
build process.

File: stow.info, Node: Cygnus Software, Next: Perl and Perl 5 Modules, Prev: Other FSF Software, Up: Compile-time vs Install-time
File: stow.info, Node: Cygnus Software, Next: Perl and Perl 5 Modules, Prev: Other FSF Software, Up: Compile-time vs. Install-time
12.4 Cygnus Software
====================
@ -1044,7 +1088,7 @@ recompiling files. Usually it will work just fine; otherwise, install
manually.

File: stow.info, Node: Perl and Perl 5 Modules, Prev: Cygnus Software, Up: Compile-time vs Install-time
File: stow.info, Node: Perl and Perl 5 Modules, Prev: Cygnus Software, Up: Compile-time vs. Install-time
12.5 Perl and Perl 5 Modules
============================
@ -1129,7 +1173,7 @@ convention, you can simply do this:
xargs rm

File: stow.info, Node: Bootstrapping, Next: Reporting Bugs, Prev: Compile-time vs Install-time, Up: Top
File: stow.info, Node: Bootstrapping, Next: Reporting Bugs, Prev: Compile-time vs. Install-time, Up: Top
13 Bootstrapping
****************
@ -1160,8 +1204,27 @@ File: stow.info, Node: Reporting Bugs, Next: Known Bugs, Prev: Bootstrapping,
14 Reporting Bugs
*****************
Please send bug reports to the current maintainers by electronic mail.
The address to use is ‘<bug-stow@gnu.org>’. Please include:
You can report bugs to the current maintainers in one of three ways:
1. Send e-mail to <bug-stow@gnu.org>.
2. File an issue in the Savannah bug tracker
(https://savannah.gnu.org/bugs/?group=stow).
3. File an issue in the GitHub project
(https://github.com/aspiers/stow/issues/).
While GitHub is arguably the most convenient of these three options,
it is not the most ethical or freedom-preserving way to host software
projects
(https://www.gnu.org/software/repo-criteria-evaluation.html#GitHub).
Therefore the GitHub project may be moved to a more ethical hosting
service (https://github.com/aspiers/stow/issues/43) in the future.
Before reporting a bug, it is recommended to check whether it is
already known, so please first *note Known Bugs::.
When reporting a new bug, please include:
• the version number of Stow (‘stow --version’);
@ -1175,11 +1238,12 @@ The address to use is ‘<bug-stow@gnu.org>’. Please include:
• the precise command you gave;
• the output from the command (preferably verbose output, obtained by
adding ‘--verbose=3’ to the Stow command line).
adding ‘--verbose=5’ to the Stow command line).
If you are really keen, consider developing a minimal test case and
creating a new test. See the ‘t/’ directory in the source for lots of
examples.
examples, and the ‘CONTRIBUTING.md’ file for a guide on how to
contribute.
Before reporting a bug, please read the manual carefully, especially
*note Known Bugs::, to see whether you're encountering something that
@ -1191,8 +1255,17 @@ File: stow.info, Node: Known Bugs, Next: GNU General Public License, Prev: Re
15 Known Bugs
*************
There are no known bugs in Stow version 2.3.2-fixbug56727! If you think
you have found one, please *note Reporting Bugs::.
Known bugs can be found in the following locations:
• the GitHub issue tracker (https://github.com/aspiers/stow/issues/)
• the Savannah bug tracker
(https://savannah.gnu.org/bugs/?group=stow)
• the bug-stow list archives
(https://lists.gnu.org/archive/html/bug-stow/)
If you think you have found a new bug, please *note Reporting Bugs::.

File: stow.info, Node: GNU General Public License, Next: Index, Prev: Known Bugs, Up: Top
@ -1919,7 +1992,7 @@ Index
[index]
* Menu:
* absolute symlink: Terminology. (line 43)
* absolute symlink: Terminology. (line 50)
* adopting existing files: Invoking Stow. (line 115)
* configuration files: Resource Files. (line 6)
* conflicts: Installing Packages. (line 85)
@ -1937,20 +2010,22 @@ Index
* ignoring files and directories: Ignore Lists. (line 6)
* installation: Installing Packages. (line 6)
* installation conflicts: Installing Packages. (line 85)
* installation image: Terminology. (line 23)
* installation image: Terminology. (line 26)
* maintenance: Target Maintenance. (line 6)
* mixing operations: Mixing Operations. (line 6)
* ownership: Installing Packages. (line 72)
* package: Terminology. (line 6)
* package directory: Terminology. (line 30)
* package name: Terminology. (line 30)
* package directory: Terminology. (line 37)
* package name: Terminology. (line 37)
* refolding trees: Deleting Packages. (line 25)
* relative symlink: Terminology. (line 43)
* relative symlink: Terminology. (line 50)
* resource files: Resource Files. (line 6)
* simulated run: Invoking Stow. (line 137)
* splitting open folded trees: Installing Packages. (line 51)
* stow directory: Terminology. (line 16)
* symlink: Terminology. (line 43)
* stow directory: Terminology. (line 19)
* symlink: Terminology. (line 50)
* symlink destination: Terminology. (line 50)
* symlink source: Terminology. (line 50)
* target directory: Terminology. (line 11)
* tree folding: Installing Packages. (line 16)
* tree refolding: Deleting Packages. (line 25)
@ -1962,43 +2037,44 @@ Index

Tag Table:
Node: Top1427
Node: Introduction3088
Ref: Introduction-Footnote-16570
Ref: Introduction-Footnote-26679
Ref: Introduction-Footnote-36777
Node: Terminology6854
Node: Invoking Stow9349
Node: Ignore Lists17276
Node: Motivation For Ignore Lists17540
Node: Types And Syntax Of Ignore Lists19071
Ref: Types And Syntax Of Ignore Lists-Footnote-122368
Ref: Types And Syntax Of Ignore Lists-Footnote-222534
Ref: Types And Syntax Of Ignore Lists-Footnote-322778
Node: Justification For Yet Another Set Of Ignore Files22927
Node: Installing Packages24542
Ref: tree folding25104
Ref: Tree unfolding27102
Node: Deleting Packages29241
Ref: tree refolding30304
Ref: Deleting Packages-Footnote-130853
Node: Conflicts31449
Ref: Deferred Operation32439
Node: Mixing Operations33039
Node: Multiple Stow Directories34031
Node: Target Maintenance35115
Node: Resource Files36398
Node: Compile-time vs Install-time38993
Node: GNU Emacs42502
Ref: GNU Emacs-Footnote-143491
Node: Other FSF Software43555
Node: Cygnus Software44336
Node: Perl and Perl 5 Modules45847
Node: Bootstrapping49476
Node: Reporting Bugs50285
Node: Known Bugs51300
Node: GNU General Public License51560
Node: Index89114
Node: Top1411
Node: Introduction3057
Ref: Introduction-Footnote-16539
Ref: Introduction-Footnote-26648
Ref: Introduction-Footnote-36746
Node: Terminology6823
Ref: symlink9312
Node: Invoking Stow11136
Node: Ignore Lists19249
Node: Motivation For Ignore Lists19513
Node: Types And Syntax Of Ignore Lists21044
Ref: Types And Syntax Of Ignore Lists-Footnote-124359
Ref: Types And Syntax Of Ignore Lists-Footnote-224525
Ref: Types And Syntax Of Ignore Lists-Footnote-324769
Node: Justification For Yet Another Set Of Ignore Files24918
Node: Installing Packages26533
Ref: tree folding27095
Ref: Tree unfolding29093
Node: Deleting Packages31232
Ref: tree refolding32295
Ref: Deleting Packages-Footnote-132844
Node: Conflicts33440
Ref: Deferred Operation34430
Node: Mixing Operations35030
Node: Multiple Stow Directories36019
Node: Target Maintenance37103
Node: Resource Files38386
Node: Compile-time vs. Install-time40982
Node: GNU Emacs44494
Ref: GNU Emacs-Footnote-145485
Node: Other FSF Software45549
Node: Cygnus Software46331
Node: Perl and Perl 5 Modules47843
Node: Bootstrapping51473
Node: Reporting Bugs52283
Node: Known Bugs54051
Node: GNU General Public License54557
Node: Index92111

End Tag Table