fsmonitor: clarify handling of directory events in callback helper
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>
Jeff Hostetler committed
Feb 26, 2024 at 21:39 UTC
7a15a62aebdf1f5aac2f74de67585908191c3bc4
1 file changed
+24
-13
fsmonitor.c
+24
-13
@@ -183,24 +183,35 @@ static int query_fsmonitor_hook(struct repository *r,
183
return result;
184
}
185
186
+/*
187
+ * The daemon can decorate directory events, such as a move or rename,
188
+ * by adding a trailing slash to the observed name. Use this to
189
+ * explicitly invalidate the entire cone under that directory.
190
+ *
191
+ * The daemon can only reliably do that if the OS FSEvent contains
192
+ * sufficient information in the event.
193
+ *
194
+ * macOS FSEvents have enough information.
195
+ *
196
+ * Other platforms may or may not be able to do it (and it might
197
+ * depend on the type of event (for example, a daemon could lstat() an
198
+ * observed pathname after a rename, but not after a delete)).
199
+ *
200
+ * If we find an exact match in the index for a path with a trailing
201
+ * slash, it means that we matched a sparse-index directory in a
202
+ * cone-mode sparse-checkout (since that's the only time we have
203
+ * directories in the index). We should never see this in practice
204
+ * (because sparse directories should not be present and therefore
205
+ * not generating FS events). Either way, we can treat them in the
206
+ * same way and just invalidate the cache-entry and the untracked
207
+ * cache (and in this case, the forward cache-entry scan won't find
208
+ * anything and it doesn't hurt to let it run).
209
+ */
210
static void handle_path_with_trailing_slash(
211
struct index_state *istate, const char *name, int pos)
212
{
213
int i;
214
191
- /*
192
- * The daemon can decorate directory events, such as
193
- * moves or renames, with a trailing slash if the OS
194
- * FS Event contains sufficient information, such as
195
- * MacOS.
196
- *
197
- * Use this to invalidate the entire cone under that
198
- * directory.
199
- *
200
- * We do not expect an exact match because the index
201
- * does not normally contain directory entries, so we
202
- * start at the insertion point and scan.
203
- */
215
if (pos < 0)
216
pos = -pos - 1;
217