mirror of
https://github.com/borgbackup/borg.git
synced 2024-12-25 01:06:50 +00:00
335 lines
12 KiB
Groff
335 lines
12 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.TH "BORG-PATTERNS" 1 "2022-10-02" "" "borg backup tool"
|
|
.SH NAME
|
|
borg-patterns \- Details regarding patterns
|
|
.SH DESCRIPTION
|
|
.sp
|
|
When specifying one or more file paths in a Borg command that supports
|
|
patterns for the respective option or argument, you can apply the
|
|
patterns described here to include only desired files and/or exclude
|
|
unwanted ones. Patterns can be used
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
for \fB\-\-exclude\fP option,
|
|
.IP \(bu 2
|
|
in the file given with \fB\-\-exclude\-from\fP option,
|
|
.IP \(bu 2
|
|
for \fB\-\-pattern\fP option,
|
|
.IP \(bu 2
|
|
in the file given with \fB\-\-patterns\-from\fP option and
|
|
.IP \(bu 2
|
|
for \fBPATH\fP arguments that explicitly support them.
|
|
.UNINDENT
|
|
.sp
|
|
Borg always stores all file paths normalized and relative to the
|
|
current recursion root. The recursion root is also named \fBPATH\fP in
|
|
Borg commands like \fIborg create\fP that do a file discovery, so do not
|
|
confuse the root with the \fBPATH\fP argument of e.g. \fIborg extract\fP\&.
|
|
.sp
|
|
Starting with Borg 1.2, paths that are matched against patterns always
|
|
appear relative. If you give \fB/absolute/\fP as root, the paths going
|
|
into the matcher will look relative like \fBabsolute/.../file.ext\fP\&.
|
|
If you give \fB\&../some/path\fP as root, the paths will look like
|
|
\fBsome/path/.../file.ext\fP\&.
|
|
.sp
|
|
File patterns support five different styles. 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 if a non\-default style is desired
|
|
or when the desired pattern starts with two alphanumeric characters
|
|
followed by a colon (i.e. \fBaa:something/*\fP).
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \fI\%Fnmatch\fP, selector \fBfm:\fP
|
|
This is the default style for \fB\-\-exclude\fP and \fB\-\-exclude\-from\fP\&.
|
|
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 (backslash for Windows and \(aq/\(aq on other systems) is not
|
|
treated specially. Wrap meta\-characters in brackets for a literal
|
|
match (i.e. \fB[?]\fP to match the literal character \(aq?\(aq). For a path
|
|
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. A leading
|
|
path separator is always removed.
|
|
.TP
|
|
.B Shell\-style patterns, selector \fBsh:\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 \fB**/\fP for matching zero or more directory
|
|
levels, \fB*\fP for matching zero or more arbitrary characters with the
|
|
exception of any path separator. A leading path separator is always removed.
|
|
.TP
|
|
.B \fI\%Regular expressions\fP, selector \fBre:\fP
|
|
Unlike 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 (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path
|
|
separators (backslash for Windows and \(aq/\(aq on other systems) in paths are
|
|
always normalized to a forward slash \(aq/\(aq before applying a pattern.
|
|
.TP
|
|
.B Path prefix, selector \fBpp:\fP
|
|
This pattern style is useful to match whole sub\-directories. The pattern
|
|
\fBpp:root/somedir\fP matches \fBroot/somedir\fP and everything therein.
|
|
A leading path separator is always removed.
|
|
.TP
|
|
.B Path full\-match, selector \fBpf:\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. \fBpf:root/file.ext\fP
|
|
matches \fBroot/file.ext\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
|
|
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
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
\fBre:\fP, \fBsh:\fP and \fBfm:\fP patterns are all implemented on top of
|
|
the Python SRE engine. It is very easy to formulate patterns for each
|
|
of these types which requires an inordinate amount of time to match
|
|
paths. If untrusted users are able to supply patterns, ensure they
|
|
cannot supply \fBre:\fP patterns. Further, ensure that \fBsh:\fP and
|
|
\fBfm:\fP patterns only contain a handful of wildcards at most.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Exclusions can be passed via the command line option \fB\-\-exclude\fP\&. When used
|
|
from within a shell, the patterns should be quoted to protect them from
|
|
expansion.
|
|
.sp
|
|
The \fB\-\-exclude\-from\fP option permits loading exclusion patterns from a text
|
|
file with one pattern per line. Lines empty or starting with the hash sign
|
|
\(aq#\(aq after removing whitespace on both ends are ignored. The optional style
|
|
selector prefix is also supported for patterns loaded from a file. Due to
|
|
whitespace removal, paths with whitespace at the beginning or end can only be
|
|
excluded using regular expressions.
|
|
.sp
|
|
To test your exclusion patterns without performing an actual backup you can
|
|
run \fBborg create \-\-list \-\-dry\-run ...\fP\&.
|
|
.sp
|
|
Examples:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
# Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq:
|
|
$ borg create \-e \(aq*.o\(aq archive /
|
|
|
|
# Exclude \(aq/home/user/junk\(aq and \(aq/home/user/subdir/junk\(aq but
|
|
# not \(aq/home/user/importantjunk\(aq or \(aq/etc/junk\(aq:
|
|
$ borg create \-e \(aqhome/*/junk\(aq archive /
|
|
|
|
# Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself:
|
|
$ borg create \-e home/user/cache/ archive /
|
|
|
|
# The file \(aq/home/user/cache/important\(aq is *not* backed up:
|
|
$ borg create \-e home/user/cache/ archive / /home/user/cache/important
|
|
|
|
# The contents of directories in \(aq/home\(aq are not backed up when their name
|
|
# ends in \(aq.tmp\(aq
|
|
$ borg create \-\-exclude \(aqre:^home/[^/]+\e.tmp/\(aq archive /
|
|
|
|
# Load exclusions from file
|
|
$ cat >exclude.txt <<EOF
|
|
# Comment line
|
|
home/*/junk
|
|
*.tmp
|
|
fm:aa:something/*
|
|
re:^home/[^/]+\e.tmp/
|
|
sh:home/*/.thumbnails
|
|
# Example with spaces, no need to escape as it is processed by borg
|
|
some file with spaces.txt
|
|
EOF
|
|
$ borg create \-\-exclude\-from exclude.txt archive /
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
A more general and easier to use way to define filename matching patterns
|
|
exists with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using
|
|
these, you may specify the backup roots, default pattern styles and
|
|
patterns for inclusion and exclusion.
|
|
.INDENT 0.0
|
|
.TP
|
|
.B Root path prefix \fBR\fP
|
|
A recursion root path starts with the prefix \fBR\fP, followed by a path
|
|
(a plain path, not a file pattern). Use this prefix to have the root
|
|
paths in the patterns file rather than as command line arguments.
|
|
.TP
|
|
.B Pattern style prefix \fBP\fP
|
|
To change the default pattern style, use the \fBP\fP prefix, followed by
|
|
the pattern style abbreviation (\fBfm\fP, \fBpf\fP, \fBpp\fP, \fBre\fP, \fBsh\fP).
|
|
All patterns following this line will use this style until another style
|
|
is specified.
|
|
.TP
|
|
.B Exclude pattern prefix \fB\-\fP
|
|
Use the prefix \fB\-\fP, followed by a pattern, to define an exclusion.
|
|
This has the same effect as the \fB\-\-exclude\fP option.
|
|
.TP
|
|
.B Exclude no\-recurse pattern prefix \fB!\fP
|
|
Use the prefix \fB!\fP, followed by a pattern, to define an exclusion
|
|
that does not recurse into subdirectories. This saves time, but
|
|
prevents include patterns to match any files in subdirectories.
|
|
.TP
|
|
.B Include pattern prefix \fB+\fP
|
|
Use the prefix \fB+\fP, followed by a pattern, to define inclusions.
|
|
This is useful to include paths that are covered in an exclude
|
|
pattern and would otherwise not be backed up.
|
|
.UNINDENT
|
|
.sp
|
|
The first matching pattern is used, so if an include pattern matches
|
|
before an exclude pattern, the file is backed up. Note that a no\-recurse
|
|
exclude stops examination of subdirectories so that potential includes
|
|
will not match \- use normal excludes for such use cases.
|
|
.sp
|
|
\fBTip: You can easily test your patterns with \-\-dry\-run and \-\-list\fP:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ borg create \-\-dry\-run \-\-list \-\-patterns\-from patterns.txt archive
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
This will list the considered files one per line, prefixed with a
|
|
character that indicates the action (e.g. \(aqx\(aq for excluding, see
|
|
\fBItem flags\fP in \fIborg create\fP usage docs).
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
It\(aqs possible that a sub\-directory/file is matched while parent
|
|
directories are not. In that case, parent directories are not backed
|
|
up and thus their user, group, permission, etc. cannot be restored.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Patterns (\fB\-\-pattern\fP) and excludes (\fB\-\-exclude\fP) from the command line are
|
|
considered first (in the order of appearance). Then patterns from \fB\-\-patterns\-from\fP
|
|
are added. Exclusion patterns from \fB\-\-exclude\-from\fP files are appended last.
|
|
.sp
|
|
Examples:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
# 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 archive pics
|
|
|
|
# backup only JPG/JPEG files (case insensitive) in all home directories:
|
|
borg create \-\-pattern \(aq+ re:\e.jpe?g(?i)$\(aq archive /home
|
|
|
|
# backup homes, but exclude big downloads (like .ISO files) or hidden files:
|
|
borg create \-\-exclude \(aqre:\e.iso(?i)$\(aq \-\-exclude \(aqsh:home/**/.*\(aq archive /home
|
|
|
|
# use a file with patterns (recursion root \(aq/\(aq via command line):
|
|
borg create \-\-patterns\-from patterns.lst archive /
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The patterns.lst file could look like that:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
# \(dqsh:\(dq pattern style is the default
|
|
# exclude caches
|
|
\- home/*/.cache
|
|
# include susans home
|
|
+ home/susan
|
|
# also back up this exact file
|
|
+ pf:home/bobby/specialfile.txt
|
|
# don\(aqt backup the other home directories
|
|
\- home/*
|
|
# don\(aqt even look in /dev, /proc, /run, /sys, /tmp (note: would exclude files like /device, too)
|
|
! re:^(dev|proc|run|sys|tmp)
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
You can specify recursion roots either on the command line or in a patternfile:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
# these two commands do the same thing
|
|
borg create \-\-exclude home/bobby/junk archive /home/bobby /home/susan
|
|
borg create \-\-patterns\-from patternfile.lst archive
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
patternfile.lst:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
# note that excludes use fm: by default and patternfiles use sh: by default.
|
|
# therefore, we need to specify fm: to have the same exact behavior.
|
|
P fm
|
|
R /home/bobby
|
|
R /home/susan
|
|
\- home/bobby/junk
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
This allows you to share the same patterns between multiple repositories
|
|
without needing to specify them on the command line.
|
|
.SH AUTHOR
|
|
The Borg Collective
|
|
.\" Generated by docutils manpage writer.
|
|
.
|