#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.

6 files changed, 13 insertions, 9 deletions

diff --git a/docs/changes.rst b/docs/changes.rst
index 2c989bdd..71648a70 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 b22ce60a..3ed3cd46 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 97accf8d..258a7fb7 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 d1af43b4..02b99a43 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 52fad663..3a7c37b4 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 06d2748e..16906d7e 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/<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)