mark --pattern, --patterns-from as experimental

docs/usage/create.rst.inc

@@ -41,9 +41,9 @@ Exclusion options
     ``--keep-exclude-tags``, ``--keep-tag-files``
         | if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
     ``--pattern PATTERN``
-        | include/exclude paths matching PATTERN
+        | experimental: include/exclude paths matching PATTERN
     ``--patterns-from PATTERNFILE``
-        | read include/exclude patterns from PATTERNFILE, one per line
+        | experimental: read include/exclude patterns from PATTERNFILE, one per line
 
 Filesystem options
     ``-x``, ``--one-file-system``

docs/usage/diff.rst.inc

@@ -39,9 +39,9 @@ Exclusion options
     ``--keep-exclude-tags``, ``--keep-tag-files``
         | if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
     ``--pattern PATTERN``
-        | include/exclude paths matching PATTERN
+        | experimental: include/exclude paths matching PATTERN
     ``--patterns-from PATTERNFILE``
-        | read include/exclude patterns from PATTERNFILE, one per line
+        | experimental: read include/exclude patterns from PATTERNFILE, one per line
 
 Description
 ~~~~~~~~~~~

docs/usage/export-tar.rst.inc

@@ -26,9 +26,9 @@ optional arguments
     ``--exclude-from EXCLUDEFILE``
         | read exclude patterns from EXCLUDEFILE, one per line
     ``--pattern PATTERN``
-        | include/exclude paths matching PATTERN
+        | experimental: include/exclude paths matching PATTERN
     ``--patterns-from PATTERNFILE``
-        | read include/exclude patterns from PATTERNFILE, one per line
+        | experimental: read include/exclude patterns from PATTERNFILE, one per line
     ``--strip-components NUMBER``
         | Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
 

docs/usage/extract.rst.inc

@@ -24,9 +24,9 @@ optional arguments
     ``--exclude-from EXCLUDEFILE``
         | read exclude patterns from EXCLUDEFILE, one per line
     ``--pattern PATTERN``
-        | include/exclude paths matching PATTERN
+        | experimental: include/exclude paths matching PATTERN
     ``--patterns-from PATTERNFILE``
-        | read include/exclude patterns from PATTERNFILE, one per line
+        | experimental: read include/exclude patterns from PATTERNFILE, one per line
     ``--numeric-owner``
         | only obey numeric user and group identifiers
     ``--strip-components NUMBER``

docs/usage/help.rst.inc

@@ -30,7 +30,7 @@ two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
     must match from the start to just before a path separator. Except
     for the root path, paths will never end in the path separator when
     matching is attempted.  Thus, if a given pattern ends in a path
-    separator, a '*' is appended before matching is attempted.
+    separator, a '\*' is appended before matching is attempted.
 
 Shell-style patterns, selector `sh:`
 
@@ -113,39 +113,40 @@ Examples::
     EOF
     $ borg create --exclude-from exclude.txt backup /
 
-
-A more general and easier to use way to define filename matching patterns exists
-with the `--pattern` and `--patterns-from` options. Using these, you may specify
-the backup roots (starting points) and patterns for inclusion/exclusion. A
-root path starts with the prefix `R`, followed by a path (a plain path, not a
-file pattern). An include rule starts with the prefix +, an exclude rule starts
-with the prefix -, both followed by a pattern.
-Inclusion patterns are useful to include paths that are contained in an excluded
-path. The first matching pattern is used so if an include pattern matches before
-an exclude pattern, the file is backed up.
-
-Note that the default pattern style for `--pattern` and `--patterns-from` is
-shell style (`sh:`), so those patterns behave similar to rsync include/exclude
-patterns. The pattern style can be set via the `P` prefix.
-
-Patterns (`--pattern`) and excludes (`--exclude`) from the command line are
-considered first (in the order of appearance). Then patterns from `--patterns-from`
-are added. Exclusion patterns from `--exclude-from` files are appended last.
-
-An example `--patterns-from` file could look like that::
-
-    # "sh:" pattern style is the default, so the following line is not needed:
-    P sh
-    R /
-    # can be rebuild
-    - /home/*/.cache
-    # they're downloads for a reason
-    - /home/*/Downloads
-    # susan is a nice person
-    # include susans home
-    + /home/susan
-    # don't backup the other home directories
-    - /home/*
+.. container:: experimental
+
+    A more general and easier to use way to define filename matching patterns exists
+    with the experimental `--pattern` and `--patterns-from` options. Using these, you
+    may specify the backup roots (starting points) and patterns for inclusion/exclusion.
+    A root path starts with the prefix `R`, followed by a path (a plain path, not a
+    file pattern). An include rule starts with the prefix +, an exclude rule starts
+    with the prefix -, both followed by a pattern.
+    Inclusion patterns are useful to include paths that are contained in an excluded
+    path. The first matching pattern is used so if an include pattern matches before
+    an exclude pattern, the file is backed up.
+
+    Note that the default pattern style for `--pattern` and `--patterns-from` is
+    shell style (`sh:`), so those patterns behave similar to rsync include/exclude
+    patterns. The pattern style can be set via the `P` prefix.
+
+    Patterns (`--pattern`) and excludes (`--exclude`) from the command line are
+    considered first (in the order of appearance). Then patterns from `--patterns-from`
+    are added. Exclusion patterns from `--exclude-from` files are appended last.
+
+    An example `--patterns-from` file could look like that::
+
+        # "sh:" pattern style is the default, so the following line is not needed:
+        P sh
+        R /
+        # can be rebuild
+        - /home/*/.cache
+        # they're downloads for a reason
+        - /home/*/Downloads
+        # susan is a nice person
+        # include susans home
+        + /home/susan
+        # don't backup the other home directories
+        - /home/*
 
 .. _borg_placeholders:
 

docs/usage/list.rst.inc

@@ -50,9 +50,9 @@ Exclusion options
     ``--keep-exclude-tags``, ``--keep-tag-files``
         | if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
     ``--pattern PATTERN``
-        | include/exclude paths matching PATTERN
+        | experimental: include/exclude paths matching PATTERN
     ``--patterns-from PATTERNFILE``
-        | read include/exclude patterns from PATTERNFILE, one per line
+        | experimental: read include/exclude patterns from PATTERNFILE, one per line
 
 Description
 ~~~~~~~~~~~

docs/usage/recreate.rst.inc

@@ -39,9 +39,9 @@ Exclusion options
     ``--keep-exclude-tags``, ``--keep-tag-files``
         | if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
     ``--pattern PATTERN``
-        | include/exclude paths matching PATTERN
+        | experimental: include/exclude paths matching PATTERN
     ``--patterns-from PATTERNFILE``
-        | read include/exclude patterns from PATTERNFILE, one per line
+        | experimental: read include/exclude patterns from PATTERNFILE, one per line
 
 Archive options
     ``--target TARGET``

src/borg/archiver.py

@@ -1942,39 +1942,40 @@ class Archiver:
             EOF
             $ borg create --exclude-from exclude.txt backup /
 
-
-        A more general and easier to use way to define filename matching patterns exists
-        with the `--pattern` and `--patterns-from` options. Using these, you may specify
-        the backup roots (starting points) and patterns for inclusion/exclusion. A
-        root path starts with the prefix `R`, followed by a path (a plain path, not a
-        file pattern). An include rule starts with the prefix +, an exclude rule starts
-        with the prefix -, both followed by a pattern.
-        Inclusion patterns are useful to include paths that are contained in an excluded
-        path. The first matching pattern is used so if an include pattern matches before
-        an exclude pattern, the file is backed up.
-
-        Note that the default pattern style for `--pattern` and `--patterns-from` is
-        shell style (`sh:`), so those patterns behave similar to rsync include/exclude
-        patterns. The pattern style can be set via the `P` prefix.
-
-        Patterns (`--pattern`) and excludes (`--exclude`) from the command line are
-        considered first (in the order of appearance). Then patterns from `--patterns-from`
-        are added. Exclusion patterns from `--exclude-from` files are appended last.
-
-        An example `--patterns-from` file could look like that::
-
-            # "sh:" pattern style is the default, so the following line is not needed:
-            P sh
-            R /
-            # can be rebuild
-            - /home/*/.cache
-            # they're downloads for a reason
-            - /home/*/Downloads
-            # susan is a nice person
-            # include susans home
-            + /home/susan
-            # don't backup the other home directories
-            - /home/*\n\n''')
+        .. container:: experimental
+
+            A more general and easier to use way to define filename matching patterns exists
+            with the experimental `--pattern` and `--patterns-from` options. Using these, you
+            may specify the backup roots (starting points) and patterns for inclusion/exclusion.
+            A root path starts with the prefix `R`, followed by a path (a plain path, not a
+            file pattern). An include rule starts with the prefix +, an exclude rule starts
+            with the prefix -, both followed by a pattern.
+            Inclusion patterns are useful to include paths that are contained in an excluded
+            path. The first matching pattern is used so if an include pattern matches before
+            an exclude pattern, the file is backed up.
+
+            Note that the default pattern style for `--pattern` and `--patterns-from` is
+            shell style (`sh:`), so those patterns behave similar to rsync include/exclude
+            patterns. The pattern style can be set via the `P` prefix.
+
+            Patterns (`--pattern`) and excludes (`--exclude`) from the command line are
+            considered first (in the order of appearance). Then patterns from `--patterns-from`
+            are added. Exclusion patterns from `--exclude-from` files are appended last.
+
+            An example `--patterns-from` file could look like that::
+
+                # "sh:" pattern style is the default, so the following line is not needed:
+                P sh
+                R /
+                # can be rebuild
+                - /home/*/.cache
+                # they're downloads for a reason
+                - /home/*/Downloads
+                # susan is a nice person
+                # include susans home
+                + /home/susan
+                # don't backup the other home directories
+                - /home/*\n\n''')
     helptext['placeholders'] = textwrap.dedent('''
         Repository (or Archive) URLs, --prefix and --remote-path values support these
         placeholders:
@@ -2790,9 +2791,9 @@ class Archiver:
                                         'objects themselves from the backup archive')
         exclude_group.add_argument('--pattern',
                                    action=ArgparsePatternAction,
-                                   metavar="PATTERN", help='include/exclude paths matching PATTERN')
+                                   metavar="PATTERN", help='experimental: include/exclude paths matching PATTERN')
         exclude_group.add_argument('--patterns-from', action=ArgparsePatternFileAction,
-                                   metavar='PATTERNFILE', help='read include/exclude patterns from PATTERNFILE, one per line')
+                                   metavar='PATTERNFILE', help='experimental: read include/exclude patterns from PATTERNFILE, one per line')
 
         fs_group = subparser.add_argument_group('Filesystem options')
         fs_group.add_argument('-x', '--one-file-system', dest='one_file_system',
@@ -2875,9 +2876,9 @@ class Archiver:
         subparser.add_argument('--exclude-from', action=ArgparseExcludeFileAction,
                                metavar='EXCLUDEFILE', help='read exclude patterns from EXCLUDEFILE, one per line')
         subparser.add_argument('--pattern', action=ArgparsePatternAction,
-                               metavar="PATTERN", help='include/exclude paths matching PATTERN')
+                               metavar="PATTERN", help='experimental: include/exclude paths matching PATTERN')
         subparser.add_argument('--patterns-from', action=ArgparsePatternFileAction,
-                               metavar='PATTERNFILE', help='read include/exclude patterns from PATTERNFILE, one per line')
+                               metavar='PATTERNFILE', help='experimental: read include/exclude patterns from PATTERNFILE, one per line')
         subparser.add_argument('--numeric-owner', dest='numeric_owner',
                                action='store_true', default=False,
                                help='only obey numeric user and group identifiers')
@@ -2948,9 +2949,9 @@ class Archiver:
         subparser.add_argument('--exclude-from', action=ArgparseExcludeFileAction,
                                metavar='EXCLUDEFILE', help='read exclude patterns from EXCLUDEFILE, one per line')
         subparser.add_argument('--pattern', action=ArgparsePatternAction,
-                               metavar="PATTERN", help='include/exclude paths matching PATTERN')
+                               metavar="PATTERN", help='experimental: include/exclude paths matching PATTERN')
         subparser.add_argument('--patterns-from', action=ArgparsePatternFileAction,
-                               metavar='PATTERNFILE', help='read include/exclude patterns from PATTERNFILE, one per line')
+                               metavar='PATTERNFILE', help='experimental: read include/exclude patterns from PATTERNFILE, one per line')
         subparser.add_argument('--strip-components', dest='strip_components',
                                type=int, default=0, metavar='NUMBER',
                                help='Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.')
@@ -3024,9 +3025,9 @@ class Archiver:
                                         'objects themselves from the backup archive')
         exclude_group.add_argument('--pattern',
                                    action=ArgparsePatternAction,
-                                   metavar="PATTERN", help='include/exclude paths matching PATTERN')
+                                   metavar="PATTERN", help='experimental: include/exclude paths matching PATTERN')
         exclude_group.add_argument('--patterns-from', action=ArgparsePatternFileAction,
-                                   metavar='PATTERNFILE', help='read include/exclude patterns from PATTERNFILE, one per line')
+                                   metavar='PATTERNFILE', help='experimental: read include/exclude patterns from PATTERNFILE, one per line')
 
         rename_epilog = process_epilog("""
         This command renames an archive in the repository.
@@ -3145,9 +3146,9 @@ class Archiver:
                                         'objects themselves from the backup archive')
         exclude_group.add_argument('--pattern',
                                    action=ArgparsePatternAction,
-                                   metavar="PATTERN", help='include/exclude paths matching PATTERN')
+                                   metavar="PATTERN", help='experimental: include/exclude paths matching PATTERN')
         exclude_group.add_argument('--patterns-from', action=ArgparsePatternFileAction,
-                                   metavar='PATTERNFILE', help='read include/exclude patterns from PATTERNFILE, one per line')
+                                   metavar='PATTERNFILE', help='experimental: read include/exclude patterns from PATTERNFILE, one per line')
 
         mount_epilog = process_epilog("""
         This command mounts an archive as a FUSE filesystem. This can be useful for
@@ -3519,9 +3520,9 @@ class Archiver:
                                         'objects themselves from the backup archive')
         exclude_group.add_argument('--pattern',
                                    action=ArgparsePatternAction,
-                                   metavar="PATTERN", help='include/exclude paths matching PATTERN')
+                                   metavar="PATTERN", help='experimental: include/exclude paths matching PATTERN')
         exclude_group.add_argument('--patterns-from', action=ArgparsePatternFileAction,
-                                   metavar='PATTERNFILE', help='read include/exclude patterns from PATTERNFILE, one per line')
+                                   metavar='PATTERNFILE', help='experimental: read include/exclude patterns from PATTERNFILE, one per line')
 
         archive_group = subparser.add_argument_group('Archive options')
         archive_group.add_argument('--target', dest='target', metavar='TARGET', default=None,