Commit graph

110 commits

Author SHA1 Message Date
Adam Spiers
4cac249ddc rename $path => $target_path in node helpers
is_a_node(), is_a_dir(), is_a_link() all operate on paths within
the target directory, so make this explicit by avoiding the vague
variable name "$path".
2024-04-01 23:58:17 +01:00
Adam Spiers
2c9065995c fold_tree: rename $target parameter to $target_subdir
$target is vague and could refer to the top-level target directory,
so rename to clarify.
2024-04-01 22:39:32 +01:00
Adam Spiers
8f6a320b50 fold_tree: rename $source parameter to $pkg_subpath
$source is vague and confusing as per the manual.
2024-04-01 22:39:32 +01:00
Adam Spiers
bae7890aa5 unstow_node / unstow_existing_node: rename foldable return value
$parent is a bit vague so rename to $parent_in_pkg.
2024-04-01 22:39:32 +01:00
Adam Spiers
b3ed86d616 unstow_valid_link: rename $existing_path
Unqualified references to "path" are horribly vague, so rename to
$existing_pkg_path_from_cwd for clarity.
2024-04-01 22:39:32 +01:00
Adam Spiers
c45a0632a9 stow_node: rename $existing_path
Unqualified references to "path" are horribly vague, so rename to
$existing_pkg_path_from_cwd for clarity.
2024-04-01 22:39:32 +01:00
Adam Spiers
3c904dade2 link_owned_by_package: rename $source => $link_dest
The use of the word "source" to describe a link's destination is
confusing in the context of Stow for reasons explained in the manual.

So rename the $source variable to avoid this.
2024-04-01 22:39:32 +01:00
Adam Spiers
381fd71155 remove or rename XXX
Remove old XXX FIXMEs which tell us nothing useful and may not be
relevant any more.

Also rename another XXX to an industry-standard FIXME.
2024-04-01 22:39:32 +01:00
Adam Spiers
221449d640 unstow_node: remove redundant return 2024-04-01 22:39:32 +01:00
Adam Spiers
a337a2fcd0 Change debug indentation in some helpers
These helpers can be called at more deeply nested levels, so they
should be indented more than they were.
2024-04-01 22:39:32 +01:00
Adam Spiers
08e1c902ec unstow_link_node: rename $existing_path
Unqualified references to "path" are horribly vague, so rename to
$existing_pkg_path_from_cwd for clarity.
2024-04-01 22:39:32 +01:00
Adam Spiers
4272e7c4bb unstow_link_node: rename $existing_source => $link_dest
The use of the word "source" to describe a link's destination is
confusing in the context of Stow for reasons explained in the manual.

So rename the $existing_source variable to $link_dest avoid this.
2024-04-01 22:39:32 +01:00
Adam Spiers
4525b9447d unstow_contents: remove reference to "source"
The use of the word "source" is confusing in the context of Stow for
reasons explained in the manual.
2024-04-01 22:39:32 +01:00
Adam Spiers
a8c93487c3 stow_node: remove comments about implementation details from POD
These don't add much value, and the reference to $source was out of
date anyway.
2024-04-01 22:39:32 +01:00
Adam Spiers
b137191d27 stow_node: rename $second_source => $link_dest
The use of the word "source" to describe a link's destination is
confusing in the context of Stow for reasons explained in the manual.

So rename the $second_source variable to avoid this.
2024-04-01 22:39:32 +01:00
Adam Spiers
b5a467fd06 foldable: make more understandable
Improve variable names, POD, and add helpful comments.
2024-04-01 22:39:32 +01:00
Adam Spiers
cc521ec14e foldable: rename $path to $target_node_path
$path is horribly vague, so rename it to be more informative.
2024-04-01 22:39:32 +01:00
Adam Spiers
09a34e7272 foldable: add debug for different cases when not foldable 2024-04-01 22:39:32 +01:00
Adam Spiers
1b597999e2 read_a_link: improve variable names
$path is horribly vague, so rename to $link to be more informative.

Also the use of "$target" to describe a link's destination is very
confusing in the context of Stow for reasons explained in the manual.
So rename to $link_dest.
2024-04-01 22:39:32 +01:00
Adam Spiers
79f90d39b3 parent_link_scheduled_for_removal: tweak debug 2024-04-01 22:39:32 +01:00
Adam Spiers
6cf41850b3 foldable: rename $target => $target_subdir
The $target variable was ambiguous, as it could have referred to the
path to the target directory, or the path to a sub-directory in the
target, as well as its intended meaning of a subpath relative to the
target directory.  So rename it to try to find the balance between
clarity and verbosity.
2024-04-01 22:39:32 +01:00
Adam Spiers
2851b36df4 find_stowed_path: rename $path / $dest to $pkg_path_from_cwd
$path is horribly vague, so rename to be more informative.
2024-04-01 22:39:32 +01:00
Adam Spiers
0daf352200 unstow_node: rename $path to $pkg_path_from_cwd
$path is horribly vague, so rename to be more informative.
2024-04-01 22:39:32 +01:00
Adam Spiers
6b9bbc9cbb link_dest_within_stow_dir: rename $path to $pkg_subpath
$path is horribly vague, so rename to be more informative.
2024-04-01 22:39:32 +01:00
Adam Spiers
170d161692 find_containing_marked_stow_dir: rename $path to $pkg_path_from_cwd
$path is horribly vague, so rename to be more informative.
2024-04-01 22:39:32 +01:00
Adam Spiers
75c892abc6 unstow_* helpers: rename $path to $pkg_path_from_cwd
$path is horribly vague, so rename to be more informative.
2024-04-01 22:39:32 +01:00
Adam Spiers
c0060443ee marked_stow_dir: rename $path to $dir
It's always a directory, so make this explicit.
2024-04-01 22:39:32 +01:00
Adam Spiers
caefb641b8 find_stowed_path: reintroduce missing comment lines
These lines were accidentally removed by 84367681.
2024-04-01 22:39:32 +01:00
Adam Spiers
10c86841de stow_contents / unstow_node: rename $target => $target_sub{dir,path}
This is very similar to a previous commit which did the same rename in
stow_node().

The $target variable was ambiguous, as it could have referred to the
path to the target directory, or the path to a sub-directory in the
target, as well as its intended meaning of a subpath relative to the
target directory.  So rename it to try to find the balance between
clarity and verbosity.
2024-04-01 22:39:32 +01:00
Adam Spiers
0782be7106 Remove unstow_*_orig() functions
Refactor the compat mode code to reuse the existing unstow_contents()
and unstow_node().  This allows us to remove the parallel versions in
unstow_contents_orig() and unstow_node(), which contained a lot of
duplicated code and were a significant maintenance burden.
2024-04-01 22:39:32 +01:00
Adam Spiers
456424c560 unstow_node_orig: replace a bunch of duplicated code with unstow_link_node() 2024-04-01 22:39:32 +01:00
Adam Spiers
517384407b unstow_node: extract new unstow_existing_node() sub 2024-04-01 22:39:32 +01:00
Adam Spiers
42cc1d2e60 unstow_node: extract new unstow_link_node() sub 2024-04-01 22:39:32 +01:00
Adam Spiers
cc592bdc44 unstow_node: extract new unstow_valid_link() sub 2024-04-01 22:39:32 +01:00
Adam Spiers
1f752a3c94 stow_node: rename $target => $target_subpath
The $target variable was ambiguous, as it could have referred to the
path to the target directory, or the path to a sub-directory in the
target, as well as its intended meaning of a subpath relative to the
target directory.  So rename it to try to find the balance between
clarity and verbosity.
2024-04-01 22:39:32 +01:00
Adam Spiers
0871a483cf rename $existing_source => $existing_link_dest
Source can be ambiguous, as mentioned in the manual.
2024-04-01 00:39:18 +01:00
Adam Spiers
e0212d4f49 stow_node(): fix odd whitespace 2024-04-01 00:35:35 +01:00
Adam Spiers
f60c203c45 should_skip_target(): add docs explaining its purpose 2024-04-01 00:34:39 +01:00
Adam Spiers
c2da8b416d do_link(): improve variable names 2024-04-01 00:34:19 +01:00
Adam Spiers
bffc347a19 Remove hard tabs 2024-04-01 00:06:24 +01:00
Adam Spiers
2f762e3908 Merge commit 'pullreqs/70' into dev 2024-03-31 23:41:02 +01:00
Adam Spiers
245dc83849 Stow.pm: reformat old comment style as pod
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.
2024-03-31 23:19:08 +01:00
Adam Spiers
f4f3836c5f Stow.pm: rename $ldest to $link_dest for clarity 2024-03-31 15:38:38 +01:00
Adam Spiers
1be40c0532 Stow.pm: reformat comments
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.
2024-03-31 15:33:14 +01:00
Adam Spiers
8436768144 Eliminate erroneous warning when unstowing (#65)
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
2024-03-31 14:03:47 +01:00
Adam Spiers
541faf68eb cleanup_invalid_links: improve docs 2024-03-31 12:16:42 +01:00
Adam Spiers
a2beb7b371 Separate treatment of .stow and .nonstow marked dirs
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.
2024-03-31 12:15:53 +01:00
Adam Spiers
287d8016f6 join_paths: improve docs to clarify purpose / differences
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.
2024-03-31 12:04:09 +01:00
Adam Spiers
4d711fc4ac Make join_paths correctly handle absolute paths
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.
2024-03-31 12:02:58 +01:00
Adam Spiers
d1480195b6 Move setting of cperl-indent-level to .dir-locals.el
This removes duplication.
2024-03-31 12:02:58 +01:00