From 3bee0f0b573b964c80db157c3046d1ea2c0b4652 Mon Sep 17 00:00:00 2001
From: trapexit <trapexit@spawn.link>
Date: Fri, 24 Oct 2025 20:47:33 -0500
Subject: [PATCH] Misc docs updates (#1549)

---
 mkdocs/docs/extended_usage_patterns.md | 11 +++++++++++
 mkdocs/docs/known_issues_bugs.md       | 26 +++++++++++++++++++-------
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/mkdocs/docs/extended_usage_patterns.md b/mkdocs/docs/extended_usage_patterns.md
index 353e5c1a..d8e7c55a 100644
--- a/mkdocs/docs/extended_usage_patterns.md
+++ b/mkdocs/docs/extended_usage_patterns.md
@@ -68,6 +68,11 @@ passthrough IO or other features.
 
 ### time based expiring
 
+**NOTE:** this script is an **example**, not particularly efficient, and
+really not intended for production deployments. Until such time that
+mergerfs provides tooling for this usecase consider using
+[mergerfs-cache-mover](https://github.com/monstermuffin/mergerfs-cache-mover).
+
 Move files from cache filesystem to base pool which have an access
 time older than the supplied number of days. Replace `-atime` with
 `-amin` in the script if you want minutes rather than days.
@@ -99,6 +104,12 @@ respectively.
 
 ### percentage full expiring
 
+**NOTE:** this script is an **example**, not particularly efficient, and
+really not intended for production deployments. Until such time that
+mergerfs provides tooling for this usecase consider using
+[mergerfs-cache-mover](https://github.com/monstermuffin/mergerfs-cache-mover).
+
+
 While the cache filesystem's percentage full is above the provided
 value move the oldest file from the cache filesystem to the base pool.
 
diff --git a/mkdocs/docs/known_issues_bugs.md b/mkdocs/docs/known_issues_bugs.md
index ecfdd435..f67506ec 100644
--- a/mkdocs/docs/known_issues_bugs.md
+++ b/mkdocs/docs/known_issues_bugs.md
@@ -23,13 +23,18 @@
 
 #### Supplemental group caching
 
-Due to the overhead of
-[getgroups/setgroups](http://linux.die.net/man/2/setgroups) mergerfs
-utilizes a cache. As necessary the supplemental group information will
-be queried and cached. That cached list of groups will be used to set
-the supplement groups as necessary. Due to the high cost of querying
-the group list the default expiry for said data is 1 hour and after 12
-hours of no usage will be removed from the cache all together.
+Due to the high cost of querying supplemental groups it is necessary
+for mergerfs to cache the list. As a result if supplemental groups are
+changed while mergerfs is running the cache may become stale. This
+generally isn't a problem as these groups tend not to be changed
+often. However, the cache has a default expiry of 1 hour and after 12
+hours of no usage the cache entry will be removed altogether.
+
+See [gidcache.expire-timeout and
+gid-cache.remove-timeout](config/options.md) and the [runtime
+interface](runtime_interface.md#commands) for forcing expiry and clearing of
+the cache.
+
 
 #### Host vs Container identity
 
@@ -128,6 +133,13 @@ more compatible but could also be more performant in certain
 situations.
 
 
+### rsync
+
+This isn't specific to mergerfs but when using `--sparse, -S` option
+with rsync the block size used to read and write data changes from
+256KiB to 1KiB. This significantly impacts performance.
+
+
 ### backup software
 
 Some software, like borgbackup and others, leverage inodes as one of a