users/ignoring: Update notes on negated ignore patterns and scanning/watching (#854)

Ref syncthing/syncthing#9340

1 files changed, 38 insertions, 23 deletions

diff --git a/users/ignoring.rst b/users/ignoring.rst
index ca21bb4..d534ee7 100644
--- a/users/ignoring.rst
+++ b/users/ignoring.rst
@@ -61,14 +61,14 @@ The ``.stignore`` file contains a list of file or path patterns. The
    special meaning. For example, ``\{banana\}`` matches ``{banana}`` exactly
    and does not denote a set of alternatives as above.
 
-.. note::
+   .. 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.
+      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.
 
 -  A pattern beginning with ``/`` matches in the root of the synced folder only.
    ``/foo`` matches ``foo`` but not ``subdir/foo``.
@@ -88,6 +88,32 @@ The ``.stignore`` file contains a list of file or path patterns. The
    are *included* (that is, *not* ignored). This can be used to override
    more general patterns that follow.
 
+   .. note::
+
+      Negated patterns that can match items below the folder root will cause
+      Syncthing to traverse otherwise ignored directories. If the
+      :ref:`watcher <scanning>` is enabled, those directories will also be
+      watched. Directories ignored before the first negated pattern can
+      however be safely skipped, since the first matching pattern wins. For
+      example::
+
+         /foo
+         /bar
+         !baz
+         *
+
+      The directories ``foo`` and ``bar`` will be entirely ignored. However any
+      other directories present must be scanned entirely to find any items
+      named `baz`, despite the fact that they will be ignored due to the
+      ``*``. As a special case, top-level rooted patterns (e.g. ``!/foo``) do
+      not cause this behaviour::
+
+         !/baz
+         *
+
+      In this case, only the directory ``baz`` will be scanned, since
+      everything else is ignored by the ``*`` pattern.
+
 -  A pattern beginning with a ``(?i)`` prefix enables case-insensitive pattern
    matching. ``(?i)test`` matches ``test``, ``TEST`` and ``tEsT``. The
    ``(?i)`` prefix can be combined with other patterns, for example the
@@ -98,26 +124,15 @@ The ``.stignore`` file contains a list of file or path patterns. The
    they are preventing directory deletion. This prefix should be used by any OS
    generated files which you are happy to be removed.
 
+   .. note::
+
+      Prefixes can be specified in any order (e.g. ``(?d)(?i)``), but cannot
+      be combined in a single pair of parentheses like :strike:`(?di)`.
+
 -  A line beginning with ``//`` is a comment and has no effect. The same double
    slashes in any other place are interpreted literally, e.g. trying to do
    ``file // comment`` will make Syncthing look for a file called ``file // comment``.
 
-.. note::
-
-   Prefixes can be specified in any order (e.g. "(?d)(?i)"), but cannot be in a
-   single pair of parentheses (not ":strike:`(?di)`").
-
-.. note::
-
-   Include patterns (that begin with ``!``) cause Syncthing to traverse 
-   the entire directory tree regardless of other ignore patterns. 
-   If the :ref:`watcher <scanning>` is enabled, the entire directory 
-   tree will be watched as well.
-
-   Top-level include patterns are treated as special cases and will not force Syncthing to
-   scan (or watch) the entire directory tree. For example: ``!/foo`` is a top-level include
-   pattern, while ``!/foo/bar`` is not.
-
 Example
 -------