diff --git a/src/borg/archiver.py b/src/borg/archiver.py index f57780aee..c409ebee1 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -1790,6 +1790,15 @@ class Archiver: helptext = collections.OrderedDict() helptext['patterns'] = textwrap.dedent(''' + The path/filenames used as input for the pattern matching start from the + currently active recursion root. You usually give the recursion root(s) + when invoking borg and these can be either relative or absolute paths. + + So, when you give `relative/` as root, the paths going into the matcher + will look like `relative/.../file.ext`. When you give `/absolute/` as root, + they will look like `/absolute/.../file.ext`. This is meant when we talk + about "full path" below. + 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`` @@ -1809,8 +1818,8 @@ class Archiver: the path separator ('\\' for Windows and '/' on other systems) is not treated specially. Wrap meta-characters in brackets for a literal match (i.e. `[?]` to match the literal character `?`). For a path - to match a pattern, it must completely match from start to end, or - must match from the start to just before a path separator. Except + to match a pattern, the full path must match, or it must match + from the start of the full path 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. @@ -1824,7 +1833,7 @@ class Archiver: Regular expressions, selector `re:` Regular expressions similar to those found in Perl are supported. Unlike - shell patterns regular expressions are not required to match the complete + shell patterns regular expressions are not required to match the full path and any substring match is sufficient. It is strongly recommended to anchor patterns to the start ('^'), to the end ('$') or both. Path separators ('\\' for Windows and '/' on other systems) in paths are @@ -1834,13 +1843,13 @@ class Archiver: Path prefix, selector `pp:` This pattern style is useful to match whole sub-directories. The pattern - `pp:/data/bar` matches `/data/bar` and everything therein. + `pp:root/somedir` matches `root/somedir` and everything therein. Path full-match, selector `pf:` - This pattern style is useful to match whole paths. + This pattern style is (only) useful to match full paths. This is kind of a pseudo pattern as it can not have any variable or - unspecified parts - the full, precise path must be given. - `pf:/data/foo.txt` matches `/data/foo.txt` only. + unspecified parts - the full path must be given. + `pf:root/file.ext` matches `root/file.txt` only. Implementation note: this is implemented via very time-efficient O(1) hashtable lookups (this means you can have huge amounts of such patterns