Merge pull request #7635 from eoli3n/master

Improve patterns help

src/borg/archiver/help_cmd.py

@@ -28,15 +28,13 @@ class HelpMixIn:
 
         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 look relative like ``absolute/.../file.ext``.
+        into the matcher will start with ``absolute/``.
-        If you give ``../some/path`` as root, the paths will look like
+        If you give ``../../relative`` as root, the paths will be normalized
-        ``some/path/.../file.ext``.
+        as ``relative/``.
 
-        File patterns support five different styles. If followed by a colon ':',
+        Borg supports different pattern styles. To define a non-default
-        the first two characters of a pattern are used as a style selector.
+        style for a specific pattern, prefix it with two characters followed
-        Explicit style selection is necessary if a non-default style is desired
+        by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``).
-        or when the desired pattern starts with two alphanumeric characters
-        followed by a colon (i.e. ``aa:something/*``).
 
         `Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector ``fm:``
             This is the default style for ``--exclude`` and ``--exclude-from``.
@@ -180,6 +178,25 @@ class HelpMixIn:
         exclude stops examination of subdirectories so that potential includes
         will not match - use normal excludes for such use cases.
 
+        Example::
+
+            # Define the recursion root
+            R /
+            # Exclude all iso files in any directory
+            - **/*.iso
+            # Explicitly include all inside etc and root
+            + etc/**
+            + root/**
+            # Exclude a specific directory under each user's home directories
+            - home/*/.cache
+            # Explicitly include everything in /home
+            + home/**
+            # Explicitly exclude some directories without recursing into them
+            ! re:^(dev|proc|run|sys|tmp)
+            # Exclude all other files and directories
+            # that are not specifically included earlier.
+            - **
+
         **Tip: You can easily test your patterns with --dry-run and  --list**::
 
             $ borg create --dry-run --list --patterns-from patterns.txt archive