docs: improve borg help patterns, fixes #7144

src/borg/archiver.py

@@ -2417,15 +2417,20 @@ class Archiver:
 
     helptext = collections.OrderedDict()
     helptext['patterns'] = textwrap.dedent('''
-        The path/filenames used as input for the pattern matching start from the
+        The path/filenames used as input for the pattern matching start with the
         currently active recursion root. You usually give the recursion root(s)
         when invoking borg and these can be either relative or absolute paths.
 
-        Starting with Borg 1.2, paths that are matched against patterns always
-        appear relative. If you give ``/absolute/`` as root, the paths going
-        into the matcher will start with ``absolute/``.
-        If you give ``../../relative`` as root, the paths will be normalized
-        as ``relative/``.
+        Be careful, your patterns must match the archived paths:
+
+        - Archived paths never start with a leading slash ('/'), nor with '.', nor with '..'.
+
+          - When you back up absolute paths like ``/home/user``, the archived
+            paths start with ``home/user``.
+          - When you back up relative paths like ``./src``, the archived paths
+            start with ``src``.
+          - When you back up relative paths like ``../../src``, the archived paths
+            start with ``src``.
 
         A directory exclusion pattern can end either with or without a slash ('/').
         If it ends with a slash, such as `some/path/`, the directory will be
@@ -2436,6 +2441,8 @@ class Archiver:
         style for a specific pattern, prefix it with two characters followed
         by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``).
 
+        The default pattern style for ``--exclude`` differs from ``--pattern``, see below.
+
         `Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`
             This is the default style for ``--exclude`` and ``--exclude-from``.
             These patterns use a variant of shell pattern syntax, with '\\*' matching
@@ -2523,6 +2530,17 @@ class Archiver:
 
         Examples::
 
+            # Exclude a directory anywhere in the tree named ``steamapps/common``
+            # (and everything below it), regardless of where it appears:
+            $ borg create -e 'sh:**/steamapps/common/**' backup /
+
+            # Exclude the contents of ``/home/user/.cache``:
+            $ borg create -e 'sh:home/user/.cache/**' backup /home/user
+            $ borg create -e home/user/.cache/ backup /home/user
+
+            # The file '/home/user/.cache/important' is *not* backed up:
+            $ borg create -e home/user/.cache/ backup / /home/user/.cache/important
+
             # Exclude '/home/user/file.o' but not '/home/user/file.odt':
             $ borg create -e '*.o' backup /
 
@@ -2530,12 +2548,6 @@ class Archiver:
             # not '/home/user/importantjunk' or '/etc/junk':
             $ borg create -e 'home/*/junk' backup /
 
-            # Exclude the contents of '/home/user/cache' but not the directory itself:
-            $ borg create -e home/user/cache/ backup /
-
-            # The file '/home/user/cache/important' is *not* backed up:
-            $ borg create -e home/user/cache/ backup / /home/user/cache/important
-
             # The contents of directories in '/home' are not backed up when their name
             # ends in '.tmp'
             $ borg create --exclude 're:^home/[^/]+\\.tmp/' backup /