From 2694652e37efbb8eb718f07aaccd644bcbb94751 Mon Sep 17 00:00:00 2001 From: Thalian Date: Fri, 27 May 2022 13:21:50 +0200 Subject: [PATCH] #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. --- docs/changes.rst | 4 +++ docs/deployment/automated-local.rst | 6 ++-- docs/deployment/pull-backup.rst | 4 +-- docs/faq.rst | 2 +- docs/quickstart.rst | 4 +-- docs/usage/create.rst | 2 +- src/borg/archiver.py | 52 ++++++++++++++--------------- 7 files changed, 38 insertions(+), 36 deletions(-) diff --git a/docs/changes.rst b/docs/changes.rst index 2c989bdd7..71648a706 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -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 diff --git a/docs/deployment/automated-local.rst b/docs/deployment/automated-local.rst index b22ce60ab..3ed3cd460 100644 --- a/docs/deployment/automated-local.rst +++ b/docs/deployment/automated-local.rst @@ -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/ diff --git a/docs/deployment/pull-backup.rst b/docs/deployment/pull-backup.rst index 97accf8dd..258a7fb77 100644 --- a/docs/deployment/pull-backup.rst +++ b/docs/deployment/pull-backup.rst @@ -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 diff --git a/docs/faq.rst b/docs/faq.rst index d1af43b45..02b99a434 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -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:: diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 52fad6639..3a7c37b4f 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -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 \ diff --git a/docs/usage/create.rst b/docs/usage/create.rst index 06d2748e1..16906d7ee 100644 --- a/docs/usage/create.rst +++ b/docs/usage/create.rst @@ -19,7 +19,7 @@ Examples # Backup home directories excluding image thumbnails (i.e. only # /home//.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) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 312032b2b..491559940 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -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 <