mirror of https://github.com/borgbackup/borg.git
docs: clarify path semantics when matching, fixes #3598
This commit is contained in:
parent
cf72c9592c
commit
9b73d31a40
|
@ -1790,6 +1790,15 @@ class Archiver:
|
||||||
|
|
||||||
helptext = collections.OrderedDict()
|
helptext = collections.OrderedDict()
|
||||||
helptext['patterns'] = textwrap.dedent('''
|
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,
|
File patterns support these styles: fnmatch, shell, regular expressions,
|
||||||
path prefixes and path full-matches. By default, fnmatch is used for
|
path prefixes and path full-matches. By default, fnmatch is used for
|
||||||
``--exclude`` patterns and shell-style is used for the experimental ``--pattern``
|
``--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
|
the path separator ('\\' for Windows and '/' on other systems) is not
|
||||||
treated specially. Wrap meta-characters in brackets for a literal
|
treated specially. Wrap meta-characters in brackets for a literal
|
||||||
match (i.e. `[?]` to match the literal character `?`). For a path
|
match (i.e. `[?]` to match the literal character `?`). For a path
|
||||||
to match a pattern, it must completely match from start to end, or
|
to match a pattern, the full path must match, or it must match
|
||||||
must match from the start to just before a path separator. Except
|
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
|
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
|
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.
|
||||||
|
@ -1824,7 +1833,7 @@ class Archiver:
|
||||||
|
|
||||||
Regular expressions, selector `re:`
|
Regular expressions, selector `re:`
|
||||||
Regular expressions similar to those found in Perl are supported. Unlike
|
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
|
path and any substring match is sufficient. It is strongly recommended to
|
||||||
anchor patterns to the start ('^'), to the end ('$') or both. Path
|
anchor patterns to the start ('^'), to the end ('$') or both. Path
|
||||||
separators ('\\' for Windows and '/' on other systems) in paths are
|
separators ('\\' for Windows and '/' on other systems) in paths are
|
||||||
|
@ -1834,13 +1843,13 @@ class Archiver:
|
||||||
|
|
||||||
Path prefix, selector `pp:`
|
Path prefix, selector `pp:`
|
||||||
This pattern style is useful to match whole sub-directories. The pattern
|
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:`
|
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
|
This is kind of a pseudo pattern as it can not have any variable or
|
||||||
unspecified parts - the full, precise path must be given.
|
unspecified parts - the full path must be given.
|
||||||
`pf:/data/foo.txt` matches `/data/foo.txt` only.
|
`pf:root/file.ext` matches `root/file.txt` only.
|
||||||
|
|
||||||
Implementation note: this is implemented via very time-efficient O(1)
|
Implementation note: this is implemented via very time-efficient O(1)
|
||||||
hashtable lookups (this means you can have huge amounts of such patterns
|
hashtable lookups (this means you can have huge amounts of such patterns
|
||||||
|
|
Loading…
Reference in New Issue