]> git.ipfire.org Git - thirdparty/git.git/commitdiff
fsmonitor: clarify handling of directory events in callback helper
authorJeff Hostetler <jeffhostetler@github.com>
Mon, 26 Feb 2024 21:39:15 +0000 (21:39 +0000)
committerJunio C Hamano <gitster@pobox.com>
Mon, 26 Feb 2024 23:34:02 +0000 (15:34 -0800)
Improve documentation of the refresh callback helper function
used for directory FSEvents.

Signed-off-by: Jeff Hostetler <jeffhostetler@github.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
fsmonitor.c

index 6fecae9aeb21f5e78a2cabcb2b64f599f194c848..29cce32d81c4d621e14b6f007ba5e7601d1b18bc 100644 (file)
@@ -183,24 +183,35 @@ static int query_fsmonitor_hook(struct repository *r,
        return result;
 }
 
+/*
+ * The daemon can decorate directory events, such as a move or rename,
+ * by adding a trailing slash to the observed name.  Use this to
+ * explicitly invalidate the entire cone under that directory.
+ *
+ * The daemon can only reliably do that if the OS FSEvent contains
+ * sufficient information in the event.
+ *
+ * macOS FSEvents have enough information.
+ *
+ * Other platforms may or may not be able to do it (and it might
+ * depend on the type of event (for example, a daemon could lstat() an
+ * observed pathname after a rename, but not after a delete)).
+ *
+ * If we find an exact match in the index for a path with a trailing
+ * slash, it means that we matched a sparse-index directory in a
+ * cone-mode sparse-checkout (since that's the only time we have
+ * directories in the index).  We should never see this in practice
+ * (because sparse directories should not be present and therefore
+ * not generating FS events).  Either way, we can treat them in the
+ * same way and just invalidate the cache-entry and the untracked
+ * cache (and in this case, the forward cache-entry scan won't find
+ * anything and it doesn't hurt to let it run).
+ */
 static void handle_path_with_trailing_slash(
        struct index_state *istate, const char *name, int pos)
 {
        int i;
 
-       /*
-        * The daemon can decorate directory events, such as
-        * moves or renames, with a trailing slash if the OS
-        * FS Event contains sufficient information, such as
-        * MacOS.
-        *
-        * Use this to invalidate the entire cone under that
-        * directory.
-        *
-        * We do not expect an exact match because the index
-        * does not normally contain directory entries, so we
-        * start at the insertion point and scan.
-        */
        if (pos < 0)
                pos = -pos - 1;