diff options
Diffstat (limited to 'docs/man/borg-patterns.1')
| -rw-r--r-- | docs/man/borg-patterns.1 | 82 |
1 files changed, 72 insertions, 10 deletions
diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 646694bfc..c250a4b92 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 "2017-02-11" "" "borg backup tool" +.TH BORG-PATTERNS 1 "2017-03-26" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns . @@ -32,8 +32,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH DESCRIPTION .sp -Exclusion patterns support four separate styles, fnmatch, shell, regular -expressions and path prefixes. By default, fnmatch is used. If followed +File patterns support these styles: fnmatch, shell, regular expressions, +path prefixes and path full\-matches. By default, fnmatch is used for +\fI\-\-exclude\fP patterns and shell\-style is used for \fI\-\-pattern\fP\&. 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 @@ -42,12 +43,12 @@ two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP). \fI\%Fnmatch\fP, selector \fIfm:\fP .INDENT 0.0 .INDENT 3.5 -This is the default style. These patterns use a variant of shell -pattern syntax, with \(aq*\(aq matching any number of characters, \(aq?\(aq -matching any single character, \(aq[...]\(aq matching any single -character specified, including ranges, and \(aq[!...]\(aq matching any -character not specified. For the purpose of these patterns, the -path separator (\(aq\(aq for Windows and \(aq/\(aq on other systems) is not +This is the default style for \-\-exclude and \-\-exclude\-from. +These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching +any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq +matching any single character specified, including ranges, and \(aq[!...]\(aq +matching any character not specified. For the purpose of these patterns, +the path separator (\(aq\(aq for Windows and \(aq/\(aq on other systems) is not treated specially. Wrap meta\-characters in brackets for a literal match (i.e. \fI[?]\fP to match the literal character \fI?\fP). For a path to match a pattern, it must completely match from start to end, or @@ -61,6 +62,7 @@ separator, a \(aq*\(aq is appended before matching is attempted. Shell\-style patterns, selector \fIsh:\fP .INDENT 0.0 .INDENT 3.5 +This is the default style for \-\-pattern and \-\-patterns\-from. 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 @@ -82,7 +84,7 @@ the re module\fP\&. .UNINDENT .UNINDENT .sp -Prefix path, selector \fIpp:\fP +Path prefix, selector \fIpp:\fP .INDENT 0.0 .INDENT 3.5 This pattern style is useful to match whole sub\-directories. The pattern @@ -90,6 +92,25 @@ This pattern style is useful to match whole sub\-directories. The pattern .UNINDENT .UNINDENT .sp +Path full\-match, selector \fIpf:\fP +.INDENT 0.0 +.INDENT 3.5 +This pattern style is useful to match whole 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. +\fIpf:/data/foo.txt\fP matches \fI/data/foo.txt\fP only. +.sp +Implementation note: this is implemented via very time\-efficient O(1) +hashtable lookups (this means you can have huge amounts of such patterns +without impacting performance much). +Due to that, this kind of pattern does not respect any context or order. +If you use such a pattern to include a file, it will always be included +(if the directory recursion encounters it). +Other include/exclude patterns that would normally match will be ignored. +Same logic applies for exclude. +.UNINDENT +.UNINDENT +.sp Exclusions can be passed via the command line option \fI\-\-exclude\fP\&. When used from within a shell the patterns should be quoted to protect them from expansion. @@ -138,6 +159,47 @@ $ borg create \-\-exclude\-from exclude.txt backup / .fi .UNINDENT .UNINDENT +.sp +A more general and easier to use way to define filename matching patterns exists +with the \fI\-\-pattern\fP and \fI\-\-patterns\-from\fP options. Using these, you may specify +the backup roots (starting points) and patterns for inclusion/exclusion. A +root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a +file pattern). An include rule starts with the prefix +, an exclude rule starts +with the prefix \-, both followed by a pattern. +Inclusion patterns are useful to include pathes that are contained in an excluded +path. The first matching pattern is used so if an include pattern matches before +an exclude pattern, the file is backed up. +.sp +Note that the default pattern style for \fI\-\-pattern\fP and \fI\-\-patterns\-from\fP is +shell style (\fIsh:\fP), so those patterns behave similar to rsync include/exclude +patterns. The pattern style can be set via the \fIP\fP prefix. +.sp +Patterns (\fI\-\-pattern\fP) and excludes (\fI\-\-exclude\fP) from the command line are +considered first (in the order of appearance). Then patterns from \fI\-\-patterns\-from\fP +are added. Exclusion patterns from \fI\-\-exclude\-from\fP files are appended last. +.sp +An example \fI\-\-patterns\-from\fP file could look like that: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# "sh:" pattern style is the default, so the following line is not needed: +P sh +R / +# can be rebuild +\- /home/*/.cache +# they\(aqre downloads for a reason +\- /home/*/Downloads +# susan is a nice person +# include susans home ++ /home/susan +# don\(aqt backup the other home directories +\- /home/* +.ft P +.fi +.UNINDENT +.UNINDENT .SH AUTHOR The Borg Collective .\" Generated by docutils manpage writer. |