afa50077c9
Stow walks the package and target tree hierarchies by using mutually recursive pairs of functions: - `stow_contents()` and `stow_node()` - `unstow_contents()` and `unstow_node()` As Stow runs its planning from the target directory (`plan_*()` both call `within_target_do()`), previously the parameters for these included: - `$target_subpath` (or `$target_subdir` in the `*_node()` functions): the relative path from the target top-level directory to the target subdirectory (initially `.` at the beginning of recursion). For example, this could be `dir1/subdir1/file1`. - `$source`: the relative path from the target _subdirectory_ (N.B. _not_ top-level directory) to the package subdirectory. For example, if the relative path to the Stow directory is `../stow`, this could be `../../../stow/pkg1/dir1/subdir1/file1`. This is used when stowing to construct a new link, or when unstowing to detect whether the link can be unstowed. Each time it descends into a further subdirectory of the target and package, it appends the new path segment onto both of these, and also prefixes `$source` with another `..`. When the `--dotfiles` parameter is enabled, it adjusts `$target_subdir`, performing the `dot-foo` => `.foo` adjustment on all segments of the path in one go. In this case, `$target_subpath` could be something like `.dir1/subdir1/file1`, and the corresponding `$source` could be something like `../../../stow/pkg1/dot-dir1/subdir1/file1`. However this doesn't leave an easy way to obtain the relative path from the target _top-level_ directory to the package subdirectory (i.e. `../stow/pkg1/dot-dir1/subdir1/file1`), which is needed for checking its existence and if necessary iterating over its contents. The current implementation solves this by including an extra `$level` parameter which tracks the recursion depth, and uses that to strip the right number of leading path segments off the front of `$source`. (In the above example, it would remove `../..`.) This implementation isn't the most elegant because: - It involves adding things to `$source` and then removing them again. - It performs the `dot-` => `.` adjustment on every path segment at each level, which is overkill, since when recursing down a level, only adjustment on the final subdirectory is required since the higher segments have already had any required adjustment. This in turn requires `adjust_dotfile` to be more complex than it needs to be. It also prevents a potential future where we might want Stow to optionally start iterating from within a subdirectory of the whole package install image / target tree, avoiding adjustment at higher levels and only doing it at the levels below the starting point. - It requires passing an extra `$level` parameter which can be automatically calculated simply by counting the number of slashes in `$target_subpath`. So change the `$source` recursion parameter to instead track the relative path from the top-level package directory to the package subdirectory or file being considered for (un)stowing, and rename it to avoid the ambiguity caused by the word "source". Also automatically calculate the depth simply by counting the number of slashes, and reconstruct `$source` when needed by combining the relative path to the Stow directory with the package name and `$target_subpath`. Closes #33. |
||
|---|---|---|
| .github/workflows | ||
| automake | ||
| bin | ||
| doc | ||
| docker | ||
| lib | ||
| t | ||
| tools | ||
| .coveralls.yml | ||
| .dir-locals.el | ||
| .dumbjump | ||
| .gitignore | ||
| .travis.yml | ||
| aclocal.m4 | ||
| AUTHORS | ||
| build-docker.sh | ||
| Build.PL | ||
| configure.ac | ||
| CONTRIBUTING.md | ||
| COPYING | ||
| default-ignore-list | ||
| INSTALL.md | ||
| Makefile.am | ||
| MANIFEST | ||
| MANIFEST.SKIP | ||
| META.json | ||
| META.yml | ||
| NEWS | ||
| README.md | ||
| test-docker.sh | ||
| THANKS | ||
| TODO | ||
README for GNU Stow
This README describes GNU Stow. This is not the definitive documentation for Stow; for that, see the info manual.
Stow is a symlink farm manager program which takes distinct sets of software and/or data located in separate directories on the filesystem, and makes them all appear to be installed in a single directory tree.
Originally Stow was born to address the need to administer, upgrade,
install, and remove files in independent software packages without
confusing them with other files sharing the same file system space.
For instance, many years ago it used to be common to compile programs
such as Perl and Emacs from source and install them in /usr/local.
By using Stow, /usr/local/bin could contain symlinks to files within
/usr/local/stow/emacs/bin, /usr/local/stow/perl/bin etc., and
likewise recursively for any other subdirectories such as .../share,
.../man, and so on.
While this is useful for keeping track of system-wide and per-user
installations of software built from source, in more recent times
software packages are often managed by more sophisticated package
management software such as
rpm,
dpkg, and
Nix / GNU
Guix, or language-native
package managers such as Ruby's
gem, Python's
pip,
Javascript's npm,
and so on.
However Stow is still used not only for software package management, but also for other purposes, such as facilitating a more controlled approach to management of configuration files in the user's home directory, especially when coupled with version control systems.
Stow was inspired by Carnegie Mellon's Depot program, but is
substantially simpler and safer. Whereas Depot required database files
to keep things in sync, Stow stores no extra state between runs, so
there's no danger (as there was in Depot) of mangling directories when
file hierarchies don't match the database. Also unlike Depot, Stow will
never delete any files, directories, or links that appear in a Stow
directory (e.g., /usr/local/stow/emacs), so it's always possible
to rebuild the target tree (e.g., /usr/local).
Stow is implemented as a combination of a Perl script providing a CLI interface, and a backend Perl module which does most of the work.
You can get the latest information about Stow from the home page:
http://www.gnu.org/software/stow/
Installation
See INSTALL.md for installation instructions.
Documentation
Documentation for Stow is available
online, as is
documentation for most GNU
software. Once you have Stow
installed, you may also find more information about Stow by running
info stow or man stow, or by looking at /usr/share/doc/stow/,
/usr/local/doc/stow/, or similar directories on your system. A
brief summary is available by running stow --help.
Mailing lists
Stow has the following mailing lists:
- help-stow is for general user help and discussion.
- stow-devel is used to discuss most aspects of Stow, including development and enhancement requests.
- bug-stow is for bug reports.
Announcements about Stow are posted to info-stow and also, as with most other GNU software, to info-gnu (archive).
Security reports that should not be made immediately public can be sent directly to the maintainer. If there is no response to an urgent issue, you can escalate to the general security mailing list for advice.
The Savannah project also has a mailing lists page.
Getting involved
Please see the CONTRIBUTING.md file.
License
Stow is free software, licensed under the GNU General Public License,
which can be found in the file COPYING.
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.
Brief history and authorship
Stow was inspired by Carnegie Mellon's "Depot" program, but is
substantially simpler. Whereas Depot requires database files to keep
things in sync, Stow stores no extra state between runs, so there's no
danger (as there is in Depot) of mangling directories when file
hierarchies don't match the database. Also unlike Depot, Stow will
never delete any files, directories, or links that appear in a Stow
directory (e.g., /usr/local/stow/emacs), so it's always possible to
rebuild the target tree (e.g., /usr/local).
For a high-level overview of the contributions of the main developers
over the years, see the AUTHORS file.
For a more detailed history, please see the ChangeLog file.