From 6e0f276e75593d30ff5533c70e6f131f1ba4fa0c Mon Sep 17 00:00:00 2001
From: Ross Smith II <ross@smithii.com>
Date: Tue, 22 Apr 2025 00:28:51 -0700
Subject: [PATCH] feat(users/ignoring): Add escaping on Windows

Ref syncthing/syncthing#10058
---
 users/faq-parts/usage.rst |  2 +-
 users/ignoring.rst        | 26 ++++++++++++++++++++------
 2 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/users/faq-parts/usage.rst b/users/faq-parts/usage.rst
index 83aefe846..a12e598cc 100644
--- a/users/faq-parts/usage.rst
+++ b/users/faq-parts/usage.rst
@@ -116,7 +116,7 @@ files ``qax``, ``qbx`` and ``qcx``.
 To match an actual file *called* ``q[abc]x`` the pattern needs to "escape"
 the brackets, like so: ``q\[abc\]x``.
 
-On Windows, escaping special characters is not supported as the ``\``
+On Windows, use the ``|`` character to escape the brackets (``q|[abc|]x``), as the ``\``
 character is used as a path separator.
 
 How do I access the web GUI from another computer?
diff --git a/users/ignoring.rst b/users/ignoring.rst
index dbf22f4ff..6526ba212 100644
--- a/users/ignoring.rst
+++ b/users/ignoring.rst
@@ -63,12 +63,26 @@ The ``.stignore`` file contains a list of file or path patterns. The
 
    .. note::
 
-      Escaped characters are not supported on Windows, where ``\`` is the
-      path separator. If you still need to match files that have square or
-      curly brackets in their names, one possible workaround is to replace
-      them with ``?``, which will then match any character. For example,
-      you can type ``?banana?`` to match both ``[banana]`` and
-      ``{banana}``, and so on.
+      On Windows, ``\`` is the path separator, so use ``|`` to escape special
+      characters. For example, ``|{banana|}`` matches
+      ``{banana}``.
+
+      To use ``\`` to escape special characters (and use ``/`` as the path separator),
+      insert a ``#escape=\`` at the top of the file. Here's a short example:
+
+         | ``#escape=\``
+         | ``/foo``
+         | ``/path/bar/\{banana\}``
+         | ``/path/baz\[2\]/ex\[3\].txt``
+
+      ``#escape=\`` must be placed at the top of the file, before any patterns,
+      but leading comments, and blank lines are OK.
+
+      Any files included using ``#include`` (see below) will each need their
+      own ``#escape=\``.
+
+      Using ``#escape=\`` allows the same file to be synced and used on any
+      operating system.
 
 -  A pattern beginning with ``/`` matches in the root of the synced folder only.
    ``/foo`` matches ``foo`` but not ``subdir/foo``.