NAME¶

borg-patterns - Details regarding patterns

DESCRIPTION¶

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.

If you give /absolute/ as root, the paths going into the matcher will look relative like absolute/.../file.ext, because file paths in Borg archives are always stored normalized and relative. This means that e.g. borg create /path/to/repo ../some/path will store all files as some/path/.../file.ext and borg create /path/to/repo /home/user will store all files as home/user/.../file.ext.

A directory exclusion pattern can end either with or without a slash ('/'). If it ends with a slash, such as some/path/, the directory will be included but not its content. If it does not end with a slash, such as some/path, both the directory and content will be excluded.

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 --pattern option. For commands that support patterns in their PATH argument like (borg list), the default pattern is path prefix.

Starting with Borg 1.2, discovered fs paths are normalised, have leading slashes removed and then are matched against your patterns. Note: You need to review your include / exclude patterns and make sure they do not expect leading slashes. Borg can only deal with this for some very simple patterns by removing leading slashes there also.

If followed by a colon (':') 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. aa:something/*).

NOTE:

Exclusions can be passed via the command line option --exclude. When used from within a shell, the patterns should be quoted to protect them from expansion.

The --exclude-from option permits loading exclusion patterns from a text file with one pattern per line. Lines empty or starting with the number sign ('#') 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.

To test your exclusion patterns without performing an actual backup you can run borg create --list --dry-run ....

Examples:

# Exclude '/home/user/file.o' but not '/home/user/file.odt':
$ borg create -e '*.o' backup /
# Exclude '/home/user/junk' and '/home/user/subdir/junk' but
# not '/home/user/importantjunk' or '/etc/junk':
$ borg create -e 'home/*/junk' backup /
# Exclude the contents of '/home/user/cache' but not the directory itself:
$ borg create -e home/user/cache/ backup /
# The file '/home/user/cache/important' is *not* backed up:
$ borg create -e home/user/cache/ backup / /home/user/cache/important
# The contents of directories in '/home' are not backed up when their name
# ends in '.tmp'
$ borg create --exclude 're:^home/[^/]+\.tmp/' backup /
# Load exclusions from file
$ cat >exclude.txt <<EOF
# Comment line
home/*/junk
*.tmp
fm:aa:something/*
re:^home/[^/]+\.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 backup /

A more general and easier to use way to define filename matching patterns exists with the --pattern and --patterns-from options. Using these, you may specify the backup roots (starting points) and patterns for inclusion/exclusion. A root path starts with the prefix R, 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 -, an exclude-norecurse rule starts with !, all followed by a pattern.

NOTE:

Inclusion patterns are useful to include paths 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. If an exclude-norecurse pattern matches a directory, it won't recurse into it and won't discover any potential matches for include rules below that directory.

NOTE:

Note that the default pattern style for --pattern and --patterns-from is shell style (sh:), so those patterns behave similar to rsync include/exclude patterns. The pattern style can be set via the P prefix.

Patterns (--pattern) and excludes (--exclude) from the command line are considered first (in the order of appearance). Then patterns from --patterns-from are added. Exclusion patterns from --exclude-from files are appended last.

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
R /
# can be rebuild
- home/*/.cache
# they're downloads for a reason
- home/*/Downloads
# susan is a nice person
# include susans home
+ home/susan
# also back up this exact file
+ pf:home/bobby/specialfile.txt
# don't backup the other home directories
- home/*
# don't even look in /proc
! proc

You can specify recursion roots either on the command line or in a patternfile:

# these two commands do the same thing
borg create --exclude home/bobby/junk repo::arch /home/bobby /home/susan
borg create --patterns-from patternfile.lst repo::arch

The patternfile:

# 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

This allows you to share the same patterns between multiple repositories without needing to specify them on the command line.

AUTHOR¶

The Borg Collective