Repository: borgbackup/borg

Issue:
--exclude versus --pattern
## Have you checked borgbackup docs, FAQ, and open Github issues?

Yes

## Is this a BUG / ISSUE report or a QUESTION?

QUESTION

I have two questions about --exclude and --pattern.

- First, `--pattern` is marked "experimental" but I cannot find what it really means. Can we use it for production or is it really expected to change?

- Second, I understand very well the difference between patterns `- /proc` and `! /proc`, but I cannot find what `--exclude /proc` is really doing. Is it equivalent to `- /proc`, or `! /proc`? Does it scan the repository, or not?

Thank you. I'm truly sorry if the answers was in the docs or here but I could not find them.


Discussion:
1. considering patterns are there since quite a while now, guess we should remove the "experimental" for next release.

2. IIRC `--exclude` is like `"! pattern"` (== has **norecurse** behaviour) - especially since there is no corresponding `--include` (which would be the only reason to recurse into, looking for more stuff to back up)

Resolving patch:
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -2228,10 +2228,9 @@ def do_break_lock(self, args, repository):
 
         File patterns support these styles: fnmatch, shell, regular expressions,
         path prefixes and path full-matches. By default, fnmatch is used for
-        ``--exclude`` patterns and shell-style is used for the experimental
-        ``--pattern`` option. For commands that support patterns in their
-        ``PATH`` argument like (``borg list``), the default pattern is path
-        prefix.
+        ``--exclude`` patterns and shell-style is used for the ``--pattern``
+         option. For commands that support patterns in their ``PATH`` argument
+        like (``borg list``), the default pattern is path prefix.
 
         Starting with Borg 1.2, for all but regular expression pattern matching
         styles, all paths are treated as relative, meaning that a leading path
@@ -2351,11 +2350,9 @@ def do_break_lock(self, args, repository):
             EOF
             $ borg create --exclude-from exclude.txt backup /
 
-        .. 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.
+            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 -, an exclude-norecurse rule starts with !, all followed by a pattern.
@@ -2813,9 +2810,9 @@ def define_exclude_and_patterns(add_option, *, tag_files=False, strip_components
             add_option('--exclude-from', metavar='EXCLUDEFILE', action=ArgparseExcludeFileAction,
                        help='read exclude patterns from EXCLUDEFILE, one per line')
             add_option('--pattern', metavar='PATTERN', action=ArgparsePatternAction,
-                       help='experimental: include/exclude paths matching PATTERN')
+                       help='include/exclude paths matching PATTERN')
             add_option('--patterns-from', metavar='PATTERNFILE', action=ArgparsePatternFileAction,
-                       help='experimental: read include/exclude patterns from PATTERNFILE, one per line')
+                       help='read include/exclude patterns from PATTERNFILE, one per line')
 
             if tag_files:
                 add_option('--exclude-caches', dest='exclude_caches', action='store_true',


Test patch: