mirror/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2024-12-29 11:16:43 +00:00
Code Issues Releases Wiki Activity

Merge pull request #3679 from ThomasWaldmann/docs-pattern-option

Browse source 
docs: pattern usage clarifications
This commit is contained in:
TW 2018-03-12 15:15:43 +01:00 committed by GitHub
commit 229114170e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 26 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
src/borg/archiver.py
View file

@ -1792,6 +1792,15 @@ def do_break_lock(self, args, repository):
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``
@ -1811,8 +1820,8 @@ def do_break_lock(self, args, repository):
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.
@ -1826,7 +1835,7 @@ def do_break_lock(self, args, repository):
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
@ -1836,13 +1845,13 @@ def do_break_lock(self, args, repository):
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
@ -1925,7 +1934,16 @@ def do_break_lock(self, args, repository):
considered first (in the order of appearance). Then patterns from ``--patterns-from`` considered first (in the order of appearance). Then patterns from ``--patterns-from``
are added. Exclusion patterns from ``--exclude-from`` files are appended last. are added. Exclusion patterns from ``--exclude-from`` files are appended last.
An example ``--patterns-from`` file could look like that:: Examples::
# backup pics, but not the ones from 2018, except the good ones:
# note: using = is essential to avoid cmdline argument parsing issues.
borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
# use a file with patterns:
borg create --patterns-from patterns.lst repo::arch
The patterns.lst file could look like that::
# "sh:" pattern style is the default, so the following line is not needed: # "sh:" pattern style is the default, so the following line is not needed:
P sh P sh