mirror
/
borg
mirror of https://github.com/borgbackup/borg.git
1
0
Fork 0
Code Issues Releases Wiki Activity

[DOCS] Add note about patterns and stored paths, #4160 

Add a section that explains storage of relative paths and how patterns can be used arbitrarily since Borg 1.2.
This commit is contained in:
Thalian 2020-04-19 12:20:46 +02:00
parent ba154d1104
commit f4f1a75a15
1 changed files with 27 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
src/borg/archiver.py
View File

@ -2066,17 +2066,27 @@ class Archiver:
when invoking borg and these can be either relative or absolute paths. 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 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, will look like `relative/.../file.ext`. When you give `/absolute/` as
they will look like `/absolute/.../file.ext`. This is meant when we talk root, they will look like `/absolute/.../file.ext`.
about "full path" below.
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`.
File patterns support these styles: fnmatch, shell, regular expressions, File patterns support these styles: fnmatch, shell, regular expressions,
path prefixes and path full-matches. By default, fnmatch is used for path prefixes and path full-matches. By default, fnmatch is used for
``--exclude`` patterns and shell-style is used for the experimental ``--pattern`` ``--exclude`` patterns and shell-style is used for the experimental
option. ``--pattern`` option.
If followed by a colon (':') the first two characters of a pattern are used as a Starting with Borg 1.2, for all but regular expression pattern matching
style selector. Explicit style selection is necessary when a 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.
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 non-default style is desired or when the desired pattern starts with
two alphanumeric characters followed by a colon (i.e. `aa:something/*`). two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
@ -2093,14 +2103,15 @@ class Archiver:
from the start of the full path to just before a path separator. Except 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 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 matching is attempted. Thus, if a given pattern ends in a path
separator, a '\\*' is appended before matching is attempted. separator, a '\\*' is appended before matching is attempted. A leading
path separator is always removed.
Shell-style patterns, selector `sh:` Shell-style patterns, selector `sh:`
This is the default style for ``--pattern`` and ``--patterns-from``. This is the default style for ``--pattern`` and ``--patterns-from``.
Like fnmatch patterns these are similar to shell patterns. The difference Like fnmatch patterns these are similar to shell patterns. The difference
is that the pattern may include `**/` for matching zero or more directory is that the pattern may include `**/` for matching zero or more directory
levels, `*` for matching zero or more arbitrary characters with the levels, `*` 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.
Regular expressions, selector `re:` Regular expressions, selector `re:`
Regular expressions similar to those found in Perl are supported. Unlike Regular expressions similar to those found in Perl are supported. Unlike
@ -2114,13 +2125,14 @@ class Archiver:
Path prefix, selector `pp:` Path prefix, selector `pp:`
This pattern style is useful to match whole sub-directories. The pattern This pattern style is useful to match whole sub-directories. The pattern
`pp:root/somedir` matches `root/somedir` and everything therein. `pp:root/somedir` matches `root/somedir` and everything therein. A leading
path separator is always removed.
Path full-match, selector `pf:` Path full-match, selector `pf:`
This pattern style is (only) useful to match full 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 This is kind of a pseudo pattern as it can not have any variable or
unspecified parts - the full path must be given. unspecified parts - the full path must be given. `pf:root/file.ext` matches
`pf:root/file.ext` matches `root/file.txt` only. `root/file.txt` only. A leading path separator is always removed.
Implementation note: this is implemented via very time-efficient O(1) Implementation note: this is implemented via very time-efficient O(1)
hashtable lookups (this means you can have huge amounts of such patterns hashtable lookups (this means you can have huge amounts of such patterns
@ -2164,7 +2176,7 @@ class Archiver:
$ borg create -e '/home/*/junk' backup / $ borg create -e '/home/*/junk' backup /
# Exclude the contents of '/home/user/cache' but not the directory itself: # Exclude the contents of '/home/user/cache' but not the directory itself:
$ borg create -e /home/user/cache/ backup / $ borg create -e home/user/cache/ backup /
# The file '/home/user/cache/important' is *not* backed up: # The file '/home/user/cache/important' is *not* backed up:
$ borg create -e /home/user/cache/ backup / /home/user/cache/important $ borg create -e /home/user/cache/ backup / /home/user/cache/important
@ -2179,8 +2191,8 @@ class Archiver:
/home/*/junk /home/*/junk
*.tmp *.tmp
fm:aa:something/* fm:aa:something/*
re:^/home/[^/]\\.tmp/ re:^home/[^/]\\.tmp/
sh:/home/*/.thumbnails sh:home/*/.thumbnails
EOF EOF
$ borg create --exclude-from exclude.txt backup / $ borg create --exclude-from exclude.txt backup /