From 71b828f712aa94d7e450ea43cc0339308b0347a9 Mon Sep 17 00:00:00 2001
From: Ferdinand Thiessen <opensource@fthiessen.de>
Date: Wed, 30 Apr 2025 16:23:32 +0200
Subject: [PATCH] feat(admin): document OCC commands for WCF

Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
---
 .../windows_compatible_filenames.rst          | 19 ++++++++
 admin_manual/occ_command.rst                  | 45 +++++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/admin_manual/configuration_files/windows_compatible_filenames.rst b/admin_manual/configuration_files/windows_compatible_filenames.rst
index 6ca902f3e..b43923feb 100644
--- a/admin_manual/configuration_files/windows_compatible_filenames.rst
+++ b/admin_manual/configuration_files/windows_compatible_filenames.rst
@@ -28,6 +28,9 @@ or filenames like ``AUX.txt`` (on Windows ``AUX`` is a reserved name and cannot
 Enabling Windows compatible filenames
 -------------------------------------
 
+This feature can be enabled either by using the web interface
+or by using an ``occ`` command.
+
 .. note::
 
 	This feature works by setting a predefined set of system configuration settings.
@@ -43,6 +46,15 @@ Within the **Files compatibility** section the Windows compatibility can be enab
 .. figure:: images/files-windows-compatibility.png
    :alt: Enforce windows compatibility checkbox on the Administration - Basic settings - Files compatibility page.
 
+Using the occ command
+^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+    This command was introduced in Nextcloud 32.
+
+To quickly enable or disable the feature an :ref:`occ command <occ_files_windows_filenames>` is provided.
+
 Consequences
 ------------
 
@@ -54,3 +66,10 @@ This works by setting a pre-defined set of configuration settings:
 - ``forbidden_filename_basenames`` will be set to names reserved on Windows.
 - ``forbidden_filename_characters`` will be set to characters not valid for filenames on Windows.
 - ``forbidden_filename_extensions`` will be set to strings not allowed as trailing parts, like a trailing dot or spaces.
+
+Sanitizing invalid filenames
+----------------------------
+
+After enabling the feature the users have to manually adjust all invalid filenames
+to be able to keep working with them.
+As an alternative Nextcloud provides the :ref:`occ files:sanitize-filenames <occ_files_sanitize_filenames>` command to automatically rename all invalid files.
diff --git a/admin_manual/occ_command.rst b/admin_manual/occ_command.rst
index 36d96e3aa..7805f6fd0 100644
--- a/admin_manual/occ_command.rst
+++ b/admin_manual/occ_command.rst
@@ -974,6 +974,36 @@ This command attempts to repair such entries by querying for entries where the p
 doesn't match the expected path based on it's parent path and filename and resets it's
 path to the expected one.
 
+.. _occ_files_sanitize_filenames:
+
+Sanitize filenames
+^^^^^^^^^^^^^^^^^^
+
+This command allows to automatically rename files not matching the current file naming constraints,
+for example after enabling the :ref:`Windows compatible filenames <windows_compatible_filenames>`::
+
+ Usage:
+   files:sanitize-filenames [options] [--] [<user_id>...]
+
+ Arguments:
+   user_id                                 Limit filename sanitizing to files given user(s) have access to
+
+ Options:
+      --dry-run                            Do not actually rename any files but just check filenames.
+  -c, --char-replacement=CHAR-REPLACEMENT  Replacement for invalid character (by default space, underscore or dash is used)
+
+When running this command without parameters it will scan all files of all users
+for filenames not comply with the current filename constraints and try to automatically
+rename those files.
+Invalid characters will be replaced by default with either a space, underscore, or dash
+depending on which characters are allowed.
+If your constraints forbid all of them, then you have to provide an character replacement
+yourself by specifying the ``--char-replacement`` option.
+
+The ``--dry-run`` option allows to perform the sanitizing without the actual renaming,
+this is useful for estimating the execution time and to get an overview on what renaming
+actions will be performed.
+
 Transfer
 ^^^^^^^^
 
@@ -1028,6 +1058,21 @@ See `user documentation <https://docs.nextcloud.com/server/latest/user_manual/en
 
 .. TODO ON RELEASE: Update version number above on release
 
+.. _occ_files_windows_filenames:
+
+Toggle Windows compatibility
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The command ``occ files:windows-compatible-filenames`` can be used to toggle
+enforcing :ref:`Windows compatible filenames <windows_compatible_filenames>`::
+
+ Usage:
+   files:windows-compatible-filenames [options]
+
+ Options:
+       --enable                  enable enforcing windows compatible filenames
+       --disable                 disable enforcing windows compatible filenames
+
 .. _occ_sharing_label:
 
 Files Sharing