diff options
author | Thomas Waldmann <tw@waldmann-edv.de> | 2020-04-21 22:59:27 +0200 |
---|---|---|
committer | Thomas Waldmann <tw@waldmann-edv.de> | 2020-04-21 22:59:27 +0200 |
commit | 1581c4f9c401f64bed07b95951610649310430d1 (patch) | |
tree | 34e5de5ecda9ced142e96396320962af5ab42d9f /docs/man/borg-patterns.1 | |
parent | 17220e09ab37739b2edc07a7461f54cc48cc5ddc (diff) |
build_man
Diffstat (limited to 'docs/man/borg-patterns.1')
-rw-r--r-- | docs/man/borg-patterns.1 | 44 |
1 files changed, 28 insertions, 16 deletions
diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 08355ed74..e77e45c7f 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PATTERNS 1 "2020-04-12" "" "borg backup tool" +.TH BORG-PATTERNS 1 "2020-04-21" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns . @@ -37,17 +37,27 @@ currently active recursion root. You usually give the recursion root(s) when invoking borg and these can be either relative or absolute paths. .sp So, when you give \fIrelative/\fP as root, the paths going into the matcher -will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as root, -they will look like \fI/absolute/.../file.ext\fP\&. This is meant when we talk -about "full path" below. +will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as +root, they will look like \fI/absolute/.../file.ext\fP\&. +.sp +File paths in Borg archives are always stored normalized and relative. +This means that e.g. \fBborg create /path/to/repo ../some/path\fP will +store all files as \fIsome/path/.../file.ext\fP and \fBborg create +/path/to/repo /home/user\fP will store all files as +\fIhome/user/.../file.ext\fP\&. .sp File patterns support these styles: fnmatch, shell, regular expressions, path prefixes and path full\-matches. By default, fnmatch is used for -\fB\-\-exclude\fP patterns and shell\-style is used for the experimental \fB\-\-pattern\fP -option. +\fB\-\-exclude\fP patterns and shell\-style is used for the experimental +\fB\-\-pattern\fP option. +.sp +Starting with Borg 1.2, for all but regular expression pattern matching +styles, all paths are treated as relative, meaning that a leading path +separator is removed after normalizing and before matching. This allows +you to use absolute or relative patterns arbitrarily. .sp -If followed by a colon (\(aq:\(aq) the first two characters of a pattern are used as a -style selector. Explicit style selection is necessary when a +If followed by a colon (\(aq:\(aq) the first two characters of a pattern are +used as a style selector. Explicit style selection is necessary when a non\-default style is desired or when the desired pattern starts with two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP). .INDENT 0.0 @@ -65,14 +75,15 @@ 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 \(aq*\(aq is appended before matching is attempted. +separator, a \(aq*\(aq is appended before matching is attempted. A leading +path separator is always removed. .TP .B Shell\-style patterns, selector \fIsh:\fP This is the default style for \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP\&. Like fnmatch patterns these are similar to shell patterns. The difference is that the pattern may include \fI**/\fP for matching zero or more directory levels, \fI*\fP for matching zero or more arbitrary characters with the -exception of any path separator. +exception of any path separator. A leading path separator is always removed. .TP .B Regular expressions, selector \fIre:\fP Regular expressions similar to those found in Perl are supported. Unlike @@ -86,13 +97,14 @@ the re module\fP\&. .TP .B Path prefix, selector \fIpp:\fP This pattern style is useful to match whole sub\-directories. The pattern -\fIpp:root/somedir\fP matches \fIroot/somedir\fP and everything therein. +\fIpp:root/somedir\fP matches \fIroot/somedir\fP and everything therein. A leading +path separator is always removed. .TP .B Path full\-match, selector \fIpf:\fP 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 path must be given. -\fIpf:root/file.ext\fP matches \fIroot/file.txt\fP only. +unspecified parts \- the full path must be given. \fIpf:root/file.ext\fP matches +\fIroot/file.txt\fP only. A leading path separator is always removed. .sp Implementation note: this is implemented via very time\-efficient O(1) hashtable lookups (this means you can have huge amounts of such patterns @@ -144,7 +156,7 @@ $ borg create \-e \(aq*.o\(aq backup / $ borg create \-e \(aq/home/*/junk\(aq backup / # Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself: -$ borg create \-e /home/user/cache/ backup / +$ borg create \-e home/user/cache/ backup / # The file \(aq/home/user/cache/important\(aq is *not* backed up: $ borg create \-e /home/user/cache/ backup / /home/user/cache/important @@ -159,8 +171,8 @@ $ cat >exclude.txt <<EOF /home/*/junk *.tmp fm:aa:something/* -re:^/home/[^/]\e.tmp/ -sh:/home/*/.thumbnails +re:^home/[^/]\e.tmp/ +sh:home/*/.thumbnails EOF $ borg create \-\-exclude\-from exclude.txt backup / .ft P |