From 78860ba46bf1a367ec5dd34409deed809e7fc57f Mon Sep 17 00:00:00 2001
From: CJ van den Berg <cj@vdbonline.com>
Date: Thu, 26 Mar 2026 22:31:14 +0100
Subject: [PATCH] docs: clarify per-backend rename semantics

---
 src/types.zig  | 21 ++++++++++++++++-----
 test_manual.sh | 16 ++++++++++++++++
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/src/types.zig b/src/types.zig
index 3108a80..07b64fc 100644
--- a/src/types.zig
+++ b/src/types.zig
@@ -11,11 +11,22 @@ pub const EventType = enum {
     deleted,
     /// A file or directory was renamed or moved.
     ///
-    /// INotify delivers this as a single `rename` callback with both the
-    /// source and destination paths. All other backends (kqueue, FSEvents,
-    /// Windows) cannot pair the two sides atomically and emit a `deleted`
-    /// event for the old path followed by a `created` event for the new
-    /// path instead.
+    /// Delivery varies by backend:
+    ///
+    /// - **INotify**: renames within the watched tree are delivered as a
+    ///   single atomic `rename` callback with both source and destination
+    ///   paths. A move out of the tree appears as `deleted`; a move into
+    ///   the tree appears as `created`.
+    ///
+    /// - **kqueue / kqueuedir**: when a watched *directory* is itself
+    ///   renamed, a `renamed` change event is emitted for the old directory
+    ///   path (the new path is not known). Renames of *files inside* a
+    ///   watched directory are detected indirectly via directory-level
+    ///   `NOTE_WRITE` events and appear as a `deleted` event for the old
+    ///   name followed by a `created` event for the new name.
+    ///
+    /// - **FSEvents / Windows**: each path involved in a rename receives
+    ///   its own `renamed` change event; the two sides are not paired.
     renamed,
 };
 
diff --git a/test_manual.sh b/test_manual.sh
index d20691e..12db2ac 100755
--- a/test_manual.sh
+++ b/test_manual.sh
@@ -53,6 +53,22 @@ sleep 0.4
 
 echo "[op] rmdir subdir"
 rmdir "$TESTDIR/subdir"
+sleep 0.4
+
+echo "[op] mkdir dirA"
+mkdir "$TESTDIR/dirA"
+sleep 0.4
+
+echo "[op] touch dirA/file3.txt"
+touch "$TESTDIR/dirA/file3.txt"
+sleep 0.4
+
+echo "[op] rename dirA -> dirB"
+mv "$TESTDIR/dirA" "$TESTDIR/dirB"
+sleep 0.4
+
+echo "[op] rmdir dirB (and contents)"
+rm -rf "$TESTDIR/dirB"
 sleep 0.5
 
 echo ""