As previously noted, the old comment style was difficult to edit.
It's also not idiomatic Perl style, so reformat as pod. This exposes
more of the inner workings of Stow as documentation, but that
shouldn't be a problem.
As part of this change, remove outdated and sometimes misleading
information about if/when each function throws an exception.
Some methods had comments with a prefix which made the paragraph
inconveniently narrow, and made refilling it really awkward. So
switch to a more natural comment style.
When unstowing a package, cleanup_invalid_links() is invoked to remove
any invalid links owned by Stow. It was invoking link_owned_by_package()
to check whether each existing link is owned by Stow. This in turn
called find_stowed_path() which since 40a0807185 was not allowing for
the possibility that it could be passed a symlink *not* owned by Stow
with an absolute target and consequently emitting an erroneous warning.
So remove this erroneous warning, and refactor find_stowed_path()
to use two new helper functions for detecting stow directories:
link_dest_within_stow_dir() and find_containing_marked_stow_dir().
Also refactor the logic within each to be simpler and more accurate,
and add more test cases to the corresponding parts of the test suite.
Fixes#65.
Closes#103.
https://github.com/aspiers/stow/issues/65
Placing a .stow file in a directory tells Stow that this directory
should be considered a Stow directory. This is already
well-documented.
There was an undocumented and slightly broken feature where placing a
.nonstow file in a directory was treated in exactly the same way. The
intention was for .nonstow to cause Stow to skip stowing into and
unstowing from that directory and any of its descendants. However, it
also caused Stow to consider symlinks into any of those directories as
owned by Stow, even though that was clearly not the intention. So
separate treatment of .stow and .nonstow markers, so that while both
provide protection against Stow stowing and unstowing, only .stow
affects the symlink ownership logic in find_stowed_path() and
marked_stow_dir().
Probably no one uses the undocumented .nonstow feature, so it may make
sense to remove this in future.
join_paths() is used in specific ways and has specific behaviour
required which is nuanced and not obvious at first sight. So make
this explicit for future reference.
Previously join_paths() was incorrectly handling absolute paths, for
example join_paths('a/b', '/c/d') would return 'a/b/c/d' rather than
'/c/d'. This was a problem when following a symlink in
find_stowed_path(), because if the symlink was not owned by Stow and
pointed to an absolute path, find_stowed_path() might accidentally
deem the link owned by Stow, if c/d was a valid path relative to the
current directory.
Unlike with the stow_{contents,node}{,_orig}() counterpart functions,
when unstowing, it's not necessary to pass the $stow_path parameter
because it can never differ from $self->{stow_path}.
The stow_*() functions need this for the corner case of unfolding a
tree which is stowed from a different stow directory to the one being
used for the current stowing operation (see the "Multiple Stow
Directories" section of the manual).
At first sight this parameter looks redundant since we have
$self->{stow_path}, but in one case the value can differ from that,
so mention that explicitly.
De-emphasise the package management aspects, since these days
almost everyone prefers to use modern package managers such as
rpm / dpkg / Nix for (system-wide) package management.
Also include more popular modern use cases for Stow such as management
of dotfiles and software compiled in the user's $HOME directory.
Fixes#22: https://github.com/aspiers/stow/issues/22
This is now necessary in order to prevent pause.perl.org from
complaining:
Status: Decreasing version number
=================================
module : Stow::Util
version: undef
in file: lib/Stow/Util.pm
status : Not indexed because lib/Stow/Util.pm in
A/AS/ASPIERS/Stow-v2.2.0.tar.gz has a higher version number
(0)
With Perl 5.20, installing a package with stow gives a warning like
this:
Possible precedence issue with control flow operator at
/gar/packages/stow-2.2.0/lib/perl5/site_perl/5.20.0/Stow.pm line 1736.
http://lists.gnu.org/archive/html/bug-stow/2014-06/msg00000.html
Suggested-by: Adam Sampson <ats@offog.org>
Fix the case discovered by Hiroyuki Iwatsuki where stowing fails if
the stow / target directories are non-canonical paths. For example,
on FreeBSD /home is a symlink pointing to 'usr/home', so running with
the stow directory as /home/user/local/stow and the target directory
as /home/user/local previously resulted in the stow directory path
being calculated as ../../../usr/home/user/local/stow relative to
the target.
http://article.gmane.org/gmane.comp.gnu.stow.bugs/8820
This is more in keeping with the UNIX convention of no output on success,
and is also the way Stow v1.x behaved. Thanks to Adam Sampson for the suggestion.
