From 8d917708fcf7ab22ffb01f9a57ae48b033b24835 Mon Sep 17 00:00:00 2001 From: Josh Date: Wed, 4 Mar 2026 01:20:04 -0500 Subject: [PATCH 1/2] docs(config): improve `filesystem_check_changes` explanation Signed-off-by: Josh --- config/config.sample.php | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/config/config.sample.php b/config/config.sample.php index f85a1da6a5be5..aa1e9765e6f1a 100644 --- a/config/config.sample.php +++ b/config/config.sample.php @@ -2461,14 +2461,27 @@ 'files_external_allow_create_new_local' => true, /** - * Specify how often the local filesystem (Nextcloud data/ directory and NFS - * mounts in data/) is checked for changes made outside Nextcloud. This does not - * apply to external storage. + * Controls how Nextcloud checks for out-of-band filesystem changes. * - * - ``0`` -> Never check the filesystem for outside changes, improving performance when no external changes are expected. - * - ``1`` -> Check each file or folder at most once per request, recommended for general use if outside changes are possible. + * This is a global default for filesystem change detection and affects + * freshness (detecting changes made outside of Nextcloud) versus performance. * - * Defaults to ``0`` + * - ``0`` -> Do not check during requests (fastest, but changes on the underlying + * storage may remain stale/invisible until a scan or refresh). + * - ``1`` -> Check once per path per request (higher overhead, better detection of + * out-of-band changes). + * + * Operational guidance: + * + * - Use ``0`` in controlled environments when all file writes go through Nextcloud. + * - Use ``1`` when there is a chance of direct file manipulation that bypasses Nextcloud. + * + * External Storage mounts provide a per-mount option with the same name + * (``filesystem_check_changes``). + * - If set on a mount, that value overrides this global value for that mount. + * - If not set on a mount, this global value is used as fallback/default. + * + * Defaults to ``0``. */ 'filesystem_check_changes' => 0, From 9a55567c65fd9d8c1d09072d266f5bb5aebf18f5 Mon Sep 17 00:00:00 2001 From: Josh Date: Wed, 4 Mar 2026 10:19:20 -0500 Subject: [PATCH 2/2] docs(config): further refine filesystem_check_changes description Signed-off-by: Josh --- config/config.sample.php | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/config/config.sample.php b/config/config.sample.php index aa1e9765e6f1a..3f1e5ee158a5b 100644 --- a/config/config.sample.php +++ b/config/config.sample.php @@ -2461,25 +2461,40 @@ 'files_external_allow_create_new_local' => true, /** - * Controls how Nextcloud checks for out-of-band filesystem changes. + * Controls whether Nextcloud performs any request-time checks for out-of-band + * filesystem changes. * * This is a global default for filesystem change detection and affects - * freshness (detecting changes made outside of Nextcloud) versus performance. + * freshness (detecting changes made outside Nextcloud) versus performance. * - * - ``0`` -> Do not check during requests (fastest, but changes on the underlying - * storage may remain stale/invisible until a scan or refresh). - * - ``1`` -> Check once per path per request (higher overhead, better detection of - * out-of-band changes). + * - ``0`` -> Do not check during requests (fastest). Out-of-band changes on + * underlying storage are not detected via routine request-time checks and + * may remain stale/invisible until explicit reconciliation paths run + * (for example, admin/maintenance scan-style refresh paths). + * - ``1`` -> Check once per path per request (higher overhead, better + * request-time detection of out-of-band changes). * * Operational guidance: * - * - Use ``0`` in controlled environments when all file writes go through Nextcloud. - * - Use ``1`` when there is a chance of direct file manipulation that bypasses Nextcloud. + * - Use ``0`` in controlled environments when all writes are expected to go + * through Nextcloud. + * - Use ``1`` when direct storage-side manipulation may occur outside Nextcloud. + * + * Relationship to ``filesystem_cache_readonly``: + * + * - ``filesystem_check_changes`` controls *detection frequency/policy*. + * - ``filesystem_cache_readonly`` controls whether scan/detection reconciliation + * results are written to filecache. + * + * Note: External Storage mounts provide a per-mount option with the same name + * (``filesystem_check_changes``): * - * External Storage mounts provide a per-mount option with the same name - * (``filesystem_check_changes``). * - If set on a mount, that value overrides this global value for that mount. - * - If not set on a mount, this global value is used as fallback/default. + * - If unset on a mount, this global value is used as fallback/default. + * + * Note: If direct storage-side manipulation may occur outside Nextcloud on an + * External Storage mount, it's generally more performant to enable it on the + * relevant mount rather than enabling it globally here. * * Defaults to ``0``. */