#6407 - Document Borg 1.2 pattern behavior change

Make clear that absolute paths always go into the matcher as if they are relative (without leading slash). Adapt all examples accordingly.

fixes #6407

docs/changes.rst

@@ -305,6 +305,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

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/
 

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

docs/faq.rst

@@ -433,7 +433,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::

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                            \

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)

src/borg/archiver.py

@@ -2489,15 +2489,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
@@ -2510,10 +2507,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
@@ -2603,26 +2601,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
@@ -2676,23 +2674,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::
@@ -2700,10 +2698,10 @@ class Archiver:
             # 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
+            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''')