From a2beb7b371aceec1e8a5ea0a0103bd77d8d92046 Mon Sep 17 00:00:00 2001
From: Adam Spiers <stow@adamspiers.org>
Date: Sat, 30 Mar 2024 14:03:56 +0000
Subject: [PATCH] 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.
---
 lib/Stow.pm.in  | 32 +++++++++++++++++++-------------
 t/unstow.t      |  2 +-
 t/unstow_orig.t |  4 ++--
 3 files changed, 22 insertions(+), 16 deletions(-)

diff --git a/lib/Stow.pm.in b/lib/Stow.pm.in
index d8d064f..5b986f1 100755
--- a/lib/Stow.pm.in
+++ b/lib/Stow.pm.in
@@ -395,7 +395,7 @@ sub stow_contents {
     # are executed.
     my $path = join_paths($stow_path, $package, $target);
 
-    return if $self->should_skip_target_which_is_stow_dir($target);
+    return if $self->should_skip_target($target);
 
     my $cwd = getcwd();
     my $msg = "Stowing contents of $path (cwd=$cwd)";
@@ -587,15 +587,16 @@ sub stow_node {
 }
 
 #===== METHOD ===============================================================
-# Name      : should_skip_target_which_is_stow_dir()
+# Name      : should_skip_target()
 # Purpose   : determine whether target is a stow directory which should
 #           : not be stowed to or unstowed from
 # Parameters: $target => relative path to symlink target from the current directory
 # Returns   : true iff target is a stow directory
 # Throws    : n/a
-# Comments  : none
+# Comments  : cwd must be the top-level target directory, otherwise
+#           : marked_stow_dir() won't work.
 #============================================================================
-sub should_skip_target_which_is_stow_dir {
+sub should_skip_target {
     my $self = shift;
     my ($target) = @_;
 
@@ -606,22 +607,27 @@ sub should_skip_target_which_is_stow_dir {
     }
 
     if ($self->marked_stow_dir($target)) {
+        warn "WARNING: skipping marked Stow directory $target\n";
+        return 1;
+    }
+
+    if (-e join_paths($target, ".nonstow")) {
         warn "WARNING: skipping protected directory $target\n";
         return 1;
     }
 
-    debug(4, 1, "$target not protected");
+    debug(4, 1, "$target not protected; shouldn't skip");
     return 0;
 }
 
+# cwd must be the top-level target directory, otherwise
+# marked_stow_dir() won't work.
 sub marked_stow_dir {
     my $self = shift;
-    my ($target) = @_;
-    for my $f (".stow", ".nonstow") {
-        if (-e join_paths($target, $f)) {
-            debug(4, 2, "$target contained $f");
-            return 1;
-        }
+    my ($path) = @_;
+    if (-e join_paths($path, ".stow")) {
+        debug(5, 5, "> $path contained .stow");
+        return 1;
     }
     return 0;
 }
@@ -642,7 +648,7 @@ sub unstow_contents_orig {
 
     my $path = join_paths($self->{stow_path}, $package, $target);
 
-    return if $self->should_skip_target_which_is_stow_dir($target);
+    return if $self->should_skip_target($target);
 
     my $cwd = getcwd();
     my $msg = "Unstowing from $target (compat mode, cwd=$cwd, stow dir=$self->{stow_path})";
@@ -762,7 +768,7 @@ sub unstow_contents {
 
     my $path = join_paths($self->{stow_path}, $package, $target);
 
-    return if $self->should_skip_target_which_is_stow_dir($target);
+    return if $self->should_skip_target($target);
 
     my $cwd = getcwd();
     my $msg = "Unstowing from $target (cwd=$cwd, stow dir=$self->{stow_path})";
diff --git a/t/unstow.t b/t/unstow.t
index 5cabf26..01a7a30 100755
--- a/t/unstow.t
+++ b/t/unstow.t
@@ -193,7 +193,7 @@ ok(
     => q(don't unlink any nodes under another stow directory)
 );
 like($stderr,
-     qr/WARNING: skipping protected directory stow2/
+     qr/WARNING: skipping marked Stow directory stow2/
      => "unstowing from ourself should skip stow");
 uncapture_stderr();
 
diff --git a/t/unstow_orig.t b/t/unstow_orig.t
index e0f595c..e893c56 100755
--- a/t/unstow_orig.t
+++ b/t/unstow_orig.t
@@ -216,8 +216,8 @@ uncapture_stderr();
 sub check_protected_dirs_skipped {
     for my $dir (qw{stow stow2}) {
         like($stderr,
-            qr/WARNING: skipping protected directory $dir/
-            => "warn when skipping protected directory $dir");
+            qr/WARNING: skipping marked Stow directory $dir/
+            => "warn when skipping marked directory $dir");
     }
     uncapture_stderr();
 }