From caab03fc13e90a96f143164630c997693070d968 Mon Sep 17 00:00:00 2001 From: Grant Stephens Date: Sat, 13 Jun 2026 05:34:04 +0100 Subject: [PATCH] docs(ignoring): document .stglobalignore shared ignore patterns Adds description and versionadded note for the new .stglobalignore file, which is synced between devices and automatically loaded alongside .stignore. Related: syncthing/syncthing#10742 Closes syncthing/syncthing#7311 Signed-off-by: Grant Stephens --- users/ignoring.rst | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/users/ignoring.rst b/users/ignoring.rst index 6fd93bd3..c730a7ec 100644 --- a/users/ignoring.rst +++ b/users/ignoring.rst @@ -11,6 +11,7 @@ Synopsis :: .stignore + .stglobalignore Description ----------- @@ -23,6 +24,16 @@ although it can ``#include`` files that *are* synchronized between devices. All patterns are relative to the synced folder root. The contents of the ``.stignore`` file must be UTF-8 encoded. +A second file called ``.stglobalignore`` can be placed in the folder root to hold +patterns that should be shared across all devices. Unlike ``.stignore``, the +``.stglobalignore`` file *is* synchronized between devices, so patterns written there +are automatically propagated when the folder syncs to a new host — no manual setup on +each device is required. Patterns from ``.stglobalignore`` are appended after those in ``.stignore``. +Because the first matching pattern wins, ``.stignore`` always takes precedence: +any pattern in ``.stignore`` — whether an ignore or a negation — will override +a conflicting pattern in ``.stglobalignore``. +If ``.stglobalignore`` does not exist the folder loads normally with no error. + .. note:: Note that ignored files can block removal of an otherwise empty directory. @@ -207,7 +218,14 @@ all files and directories called "foo", ending in a "2" or starting with .. versionadded:: 2.0.0 - Windows users can now use the pipe character (``|``) to escape - metacharacters in the ``.stignore`` file. Additionally, adding - ``#escape=X`` to the top of the file, allows users to define ``X`` + Windows users can now use the pipe character (``|``) to escape + metacharacters in the ``.stignore`` file. Additionally, adding + ``#escape=X`` to the top of the file, allows users to define ``X`` as the escape character for that particular file. + +.. versionadded:: 2.2.0 + + ``.stglobalignore`` is now automatically loaded alongside ``.stignore``. + Patterns in ``.stglobalignore`` are synced between devices, removing the + need to manually configure ignore patterns on each host. See the + description above for precedence rules.