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

#6407 - Document Borg 1.2 pattern behavior change 

Backport from master: Make clear that absolute paths always go into the matcher as if they are relative (without leading slash). Adapt all examples accordingly.
This commit is contained in:
Thalian 2022-05-27 13:21:50 +02:00
parent 371bb06dd1
commit 2694652e37
7 changed files with 38 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/changes.rst
View File

@ -260,6 +260,10 @@ and maybe just were not noticed.
Compatibility notes:
- matching of path patterns has been aligned with borg storing relative paths.
Borg archives file paths without leading slashes. Previously, include/exclude
patterns could contain leading slashes. You should check your patterns and
remove leading slashes.
- dropped support / testing for older Pythons, minimum requirement is 3.8.
In case your OS does not provide Python >= 3.8, consider using our binary,
which does not need an external Python interpreter. Or continue using

6
docs/deployment/automated-local.rst
View File

@ -136,8 +136,8 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
# This is just an example, change it however you see fit
borg create $BORG_OPTS \
--exclude /root/.cache \
--exclude /var/lib/docker/devicemapper \
--exclude root/.cache \
--exclude var/lib/docker/devicemapper \
$TARGET::$DATE-$$-system \
/ /boot
@ -145,7 +145,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
# Even if it isn't (add --exclude /home above), it probably makes sense
# to have /home in a separate archive.
borg create $BORG_OPTS \
--exclude 'sh:/home/*/.cache' \
--exclude 'sh:home/*/.cache' \
$TARGET::$DATE-$$-home \
/home/

4
docs/deployment/pull-backup.rst
View File

@ -98,9 +98,9 @@ create the backup, retaining the original paths, excluding the repository:
::
borg create --exclude /borgrepo --files-cache ctime,size /borgrepo::archive /
borg create --exclude borgrepo --files-cache ctime,size /borgrepo::archive /
For the sake of simplicity only ``/borgrepo`` is excluded here. You may want to
For the sake of simplicity only ``borgrepo`` is excluded here. You may want to
set up an exclude file with additional files and folders to be excluded. Also
note that we have to modify Borg's file change detection behaviour – SSHFS
cannot guarantee stable inode numbers, so we have to supply the

2
docs/faq.rst
View File

@ -431,7 +431,7 @@ Say you want to prune ``/var/log`` faster than the rest of
archive *names* and then implement different prune policies for
different prefixes. For example, you could have a script that does::
borg create --exclude /var/log $REPOSITORY:main-$(date +%Y-%m-%d) /
borg create --exclude var/log $REPOSITORY:main-$(date +%Y-%m-%d) /
borg create $REPOSITORY:logs-$(date +%Y-%m-%d) /var/log
Then you would have two different prune calls with different policies::

4
docs/quickstart.rst
View File

@ -182,8 +182,8 @@ backed up and that the ``prune`` command is keeping and deleting the correct bac
--show-rc \
--compression lz4 \
--exclude-caches \
--exclude '/home/*/.cache/*' \
--exclude '/var/tmp/*' \
--exclude 'home/*/.cache/*' \
--exclude 'var/tmp/*' \
\
::'{hostname}-{now}' \
/etc \

2
docs/usage/create.rst
View File

@ -19,7 +19,7 @@ Examples
# Backup home directories excluding image thumbnails (i.e. only
# /home/<one directory>/.thumbnails is excluded, not /home/*/*/.thumbnails etc.)
$ borg create /path/to/repo::my-files /home \
--exclude 'sh:/home/*/.thumbnails'
--exclude 'sh:home/*/.thumbnails'
# Backup the root filesystem into an archive named "root-YYYY-MM-DD"
# use zlib compression (good, but slow) - default is lz4 (fast, low compression ratio)

52
src/borg/archiver.py
View File

@ -2244,15 +2244,12 @@ class Archiver:
currently active recursion root. You usually give the recursion root(s)
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
will look like `relative/.../file.ext`. When you give `/absolute/` as
root, they will look like `/absolute/.../file.ext`.
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`.
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
@ -2265,10 +2262,11 @@ class Archiver:
option. For commands that support patterns in their ``PATH`` argument
like (``borg list``), the default pattern is path prefix.
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.
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
@ -2358,26 +2356,26 @@ class Archiver:
# Exclude '/home/user/junk' and '/home/user/subdir/junk' but
# not '/home/user/importantjunk' or '/etc/junk':
$ borg create -e '/home/*/junk' backup /
$ 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
$ 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 /
$ borg create --exclude 're:^home/[^/]+\\.tmp/' backup /
# Load exclusions from file
$ cat >exclude.txt <<EOF
# Comment line
/home/*/junk
home/*/junk
*.tmp
fm:aa:something/*
re:^/home/[^/]+\\.tmp/
sh:/home/*/.thumbnails
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
@ -2431,23 +2429,23 @@ class Archiver:
P sh
R /
# can be rebuild
- /home/*/.cache
- home/*/.cache
# they're downloads for a reason
- /home/*/Downloads
- home/*/Downloads
# susan is a nice person
# include susans home
+ /home/susan
+ home/susan
# also back up this exact file
+ pf:/home/bobby/specialfile.txt
+ pf:home/bobby/specialfile.txt
# don't backup the other home directories
- /home/*
- home/*
# don't even look in /proc
! /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 --exclude home/bobby/junk repo::arch /home/bobby /home/susan
borg create --patterns-from patternfile.lst repo::arch
The patternfile::
@ -2458,7 +2456,7 @@ class Archiver:
R /home/bobby
R /home/susan
- /home/bobby/junk
- home/bobby/junk
This allows you to share the same patterns between multiple repositories
without needing to specify them on the command line.\n\n''')