From 41bd6dd35b8ce14ae2f98882271c6610bcfb552c Mon Sep 17 00:00:00 2001
From: Thomas Waldmann <tw@waldmann-edv.de>
Date: Fri, 10 Oct 2025 23:09:26 +0200
Subject: [PATCH] docs: improve borg help patterns, fixes #7144

---
 src/borg/archiver.py | 36 ++++++++++++++++++++++++------------
 1 file changed, 24 insertions(+), 12 deletions(-)

diff --git a/src/borg/archiver.py b/src/borg/archiver.py
index 2114d33f9..f186babec 100644
--- a/src/borg/archiver.py
+++ b/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 /