From cf72c9592ccc0ee463f408730eadfed9f5060e96 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Fri, 9 Mar 2018 21:37:06 +0100 Subject: [PATCH 1/2] docs: add an example for --pattern usage, fixes #3661 --- src/borg/archiver.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 0f8b27c91..f57780aee 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -1923,7 +1923,16 @@ def do_break_lock(self, args, repository): 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:: + 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: P sh From 9b73d31a40ffa463eb62b9703c2d10a93d3f585c Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Fri, 9 Mar 2018 22:57:37 +0100 Subject: [PATCH 2/2] docs: clarify path semantics when matching, fixes #3598 --- src/borg/archiver.py | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) 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 @@ def do_break_lock(self, args, repository): 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 @@ def do_break_lock(self, args, repository): 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 @@ def do_break_lock(self, args, repository): 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 @@ def do_break_lock(self, args, repository): 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