From c164d6a2a38992e0332b2fd51285733ed67b82ea Mon Sep 17 00:00:00 2001
From: Antonio SJ Musumeci <trapexit@spawn.link>
Date: Wed, 6 May 2026 16:19:45 -0500
Subject: [PATCH] Document advisory locking limitation and update deprecated
 options

- Add documentation explaining that advisory file locking is not supported

- Add remember-nodes to deprecated options mapping

- Add comment explaining stat_crc32b fingerprint invalidation behavior

- Fix heading level for Host vs Container identity section
---
 mkdocs/docs/config/deprecated_options.md |  1 +
 mkdocs/docs/known_issues_bugs.md         | 26 +++++++++++++++++++++++-
 vendored/libfuse/lib/fuse.cpp            |  7 +++++++
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/mkdocs/docs/config/deprecated_options.md b/mkdocs/docs/config/deprecated_options.md
index 635a7fc8..67d502af 100644
--- a/mkdocs/docs/config/deprecated_options.md
+++ b/mkdocs/docs/config/deprecated_options.md
@@ -16,6 +16,7 @@ function or have been replaced. **They should not be used.**
 * **kernel_cache**: Use [cache.files=full](cache.md).
 * **negative_entry**: Use [cache.negative-entry](cache.md).
 * **remember**: Use `never-forget-nodes`.
+* **remember-nodes**: Use `never-forget-nodes`.
 * **noforget**: Use `never-forget-nodes`.
 * **nonempty**: Does nothing.
 * **splice_move**: Does nothing.
diff --git a/mkdocs/docs/known_issues_bugs.md b/mkdocs/docs/known_issues_bugs.md
index eba48e80..8817c5e8 100644
--- a/mkdocs/docs/known_issues_bugs.md
+++ b/mkdocs/docs/known_issues_bugs.md
@@ -2,6 +2,30 @@
 
 ## mergerfs
 
+### Advisory file locking not currently supported
+
+mergerfs does not implement POSIX or BSD advisory file locks as
+provided by FUSE. Doing so is complex because, as a union filesystem,
+it would need to forward lock requests to the underlying branches,
+which could result in blocking calls. Locally this is not a major
+concern—the kernel still manages locks for applications that all go
+through the mergerfs mount. However, if an application locks a file
+via the mergerfs mount while another locks the same file directly on
+the underlying filesystem, the locks will not interact as one might
+expect. That usage pattern is uncommon, so it is generally not a
+problem.
+
+The issue becomes more significant if you rely on locks over a remote
+filesystem like NFS across multiple hosts, because mergerfs never
+actually makes a lock call to the underlying branch. While network
+locks are possible, they are generally discouraged, so this may not be
+a huge loss either.
+
+That said, there is a strategy that could add lock support if there is
+sufficient demand, though it would probably be opt-in for performance
+and resource-usage reasons.
+
+
 ### FreeBSD version
 
 * [https://wiki.freebsd.org/FUSEFS](https://wiki.freebsd.org/FUSEFS)
@@ -27,7 +51,7 @@
     * ...
 
 
-#### Host vs Container identity
+### Host vs Container identity
 
 While **not** a bug some users have found when using containers that
 supplemental groups defined inside the container don't work as
diff --git a/vendored/libfuse/lib/fuse.cpp b/vendored/libfuse/lib/fuse.cpp
index c2fce94c..3436f9cd 100644
--- a/vendored/libfuse/lib/fuse.cpp
+++ b/vendored/libfuse/lib/fuse.cpp
@@ -1215,6 +1215,13 @@ update_stat(node_t       *node_,
 {
   uint32_t crc32b;
 
+  // This function can only invalidate an existing fingerprint; it
+  // never arms a new one. Arming (writing a non-zero CRC into
+  // state_crc32b) happens exclusively in open_auto_cache(), which is
+  // the single point that decides a file's page cache is worth
+  // retaining across opens. If stat_crc32b is 0 here the cache is
+  // already considered invalid and we have nothing to compare
+  // against.
   if(node_->stat_crc32b == 0)
     return;