Merge pull request #7223 from ThomasWaldmann/fix-docs-prefix-1.2

Fix docs / tests concerning deprecated --prefix (1.2-maint)

6 files changed, 28 insertions, 30 deletions

diff --git a/docs/faq.rst b/docs/faq.rst
index 03736ddd..786ed6e3 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -435,18 +435,19 @@ How do I configure different prune policies for different directories?
 Say you want to prune ``/var/log`` faster than the rest of
 ``/``. How do we implement that? The answer is to backup to different
 archive *names* and then implement different prune policies for
-different prefixes. For example, you could have a script that does::
+different --glob-archives matching patterns.
+
+For example, you could have a script that does::
 
     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::
 
-    borg prune --verbose --list -d 30 --prefix main- "$REPOSITORY"
-    borg prune --verbose --list -d 7  --prefix logs- "$REPOSITORY"
+    borg prune --verbose --list -d 30 --glob-archives 'main-*' "$REPOSITORY"
+    borg prune --verbose --list -d 7  --glob-archives 'logs-*' "$REPOSITORY"
 
-This will keep 7 days of logs and 30 days of everything else. Borg 1.1
-also supports the ``--glob-archives`` parameter.
+This will keep 7 days of logs and 30 days of everything else.
 
 How do I remove files from an existing backup?
 ----------------------------------------------
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 4482bdde..85f75742 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -198,7 +198,7 @@ backed up and that the ``prune`` command is keeping and deleting the correct bac
     info "Pruning repository"
 
     # Use the `prune` subcommand to maintain 7 daily, 4 weekly and 6 monthly
-    # archives of THIS machine. The '{hostname}-' prefix is very important to
+    # archives of THIS machine. The '{hostname}-*' matching is very important to
     # limit prune's operation to this machine's archives and not apply to
     # other machines' archives also:
 
@@ -208,7 +208,7 @@ backed up and that the ``prune`` command is keeping and deleting the correct bac
         --show-rc                       \
         --keep-daily    7               \
         --keep-weekly   4               \
-        --keep-monthly  6    
+        --keep-monthly  6
 
     prune_exit=$?
 
diff --git a/docs/usage/delete.rst b/docs/usage/delete.rst
index 7bd50b5d..72270cca 100644
--- a/docs/usage/delete.rst
+++ b/docs/usage/delete.rst
@@ -10,7 +10,7 @@ Examples
     $ borg compact /path/to/repo
 
     # delete all archives whose names begin with the machine's hostname followed by "-"
-    $ borg delete --prefix '{hostname}-' /path/to/repo
+    $ borg delete --glob-archives '{hostname}-*' /path/to/repo
 
     # delete all archives whose names contain "-2012-"
     $ borg delete --glob-archives '*-2012-*' /path/to/repo
diff --git a/docs/usage/prune.rst b/docs/usage/prune.rst
index 6b0ac84b..62642616 100644
--- a/docs/usage/prune.rst
+++ b/docs/usage/prune.rst
@@ -7,9 +7,9 @@ Be careful, prune is a potentially dangerous command, it will remove backup
 archives.
 
 The default of prune is to apply to **all archives in the repository** unless
-you restrict its operation to a subset of the archives using ``--prefix``.
-When using ``--prefix``, be careful to choose a good prefix - e.g. do not use a
-prefix "foo" if you do not also want to match "foobar".
+you restrict its operation to a subset of the archives using ``--glob-archives``.
+When using ``--glob-archives``, be careful to choose a good matching pattern -
+e.g. do not use "foo*" if you do not also want to match "foobar".
 
 It is strongly recommended to always run ``prune -v --list --dry-run ...``
 first so you will see what it would do without it actually doing anything.
@@ -22,7 +22,7 @@ first so you will see what it would do without it actually doing anything.
 
     # Same as above but only apply to archive names starting with the hostname
     # of the machine followed by a "-" character:
-    $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --prefix='{hostname}-' /path/to/repo
+    $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --glob-archives='{hostname}-*' /path/to/repo
     # actually free disk space:
     $ borg compact /path/to/repo
 
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
index 85ada4e7..8cc3a7b0 100644
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -327,7 +327,7 @@ class Archiver:
                 return EXIT_ERROR
         if args.repo_only and any(
            (args.verify_data, args.first, args.last, args.prefix is not None, args.glob_archives)):
-            self.print_error("--repository-only contradicts --first, --last, --prefix and --verify-data arguments.")
+            self.print_error("--repository-only contradicts --first, --last, --glob-archives, --prefix and --verify-data arguments.")
             return EXIT_ERROR
         if args.repair and args.max_duration:
             self.print_error("--repair does not allow --max-duration argument.")
@@ -2556,7 +2556,7 @@ class Archiver:
 
             borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
             borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
-            borg prune --prefix '{hostname}-' ...
+            borg prune --glob-archives '{hostname}-*' ...
 
         .. note::
             systemd uses a difficult, non-standard syntax for command lines in unit files (refer to
@@ -2948,12 +2948,11 @@ class Archiver:
                                                          'Archive filters can be applied to repository targets.')
             group = filters_group.add_mutually_exclusive_group()
             group.add_argument('-P', '--prefix', metavar='PREFIX', dest='prefix', type=PrefixSpec, action=Highlander,
-                               help='only consider archive names starting with this prefix.')
+                               help='only consider archive names starting with this prefix. (deprecated)')
             group.add_argument('-a', '--glob-archives', metavar='GLOB', dest='glob_archives',
                                type=GlobSpec, action=Highlander,
                                help='only consider archive names matching the glob. '
-                                    'sh: rules apply, see "borg help patterns". '
-                                    '``--prefix`` and ``--glob-archives`` are mutually exclusive.')
+                                    'sh: rules apply, see "borg help patterns".')
 
             if sort_by:
                 sort_by_default = 'timestamp'
@@ -3837,11 +3836,9 @@ class Archiver:
         that is how much your repository will shrink.
         Please note that the "All archives" stats refer to the state after deletion.
 
-        You can delete multiple archives by specifying their common prefix, if they
-        have one, using the ``--prefix PREFIX`` option. You can also specify a shell
-        pattern to match multiple archives using the ``--glob-archives GLOB`` option
-        (for more info on these patterns, see :ref:`borg_patterns`). Note that these
-        two options are mutually exclusive.
+        You can delete multiple archives by specifying a shell pattern to match
+        multiple archives using the ``--glob-archives GLOB`` option (for more info on
+        these patterns, see :ref:`borg_patterns`).
 
         To avoid accidentally deleting archives, especially when using glob patterns,
         it might be helpful to use the ``--dry-run`` to test out the command without
diff --git a/src/borg/testsuite/archiver.py b/src/borg/testsuite/archiver.py
index 60ce9baa..2e6f4e0a 100644
--- a/src/borg/testsuite/archiver.py
+++ b/src/borg/testsuite/archiver.py
@@ -1575,7 +1575,7 @@ class ArchiverTestCase(ArchiverTestCaseBase):
         self.cmd('create', self.repository_location + '::another_test.2', 'input')
         self.cmd('extract', '--dry-run', self.repository_location + '::test')
         self.cmd('extract', '--dry-run', self.repository_location + '::test.2')
-        self.cmd('delete', '--prefix', 'another_', self.repository_location)
+        self.cmd('delete', '--glob-archives', 'another_*', self.repository_location)
         self.cmd('delete', '--last', '1', self.repository_location)
         self.cmd('delete', self.repository_location + '::test')
         self.cmd('extract', '--dry-run', self.repository_location + '::test.2')
@@ -2259,12 +2259,12 @@ class ArchiverTestCase(ArchiverTestCaseBase):
         self.assert_in('2015-08-12-10:00-bar', output)
         self.assert_in('2015-08-12-20:00-bar', output)
 
-    def test_list_prefix(self):
+    def test_list_glob(self):
         self.cmd('init', '--encryption=repokey', self.repository_location)
         self.cmd('create', self.repository_location + '::test-1', src_dir)
         self.cmd('create', self.repository_location + '::something-else-than-test-1', src_dir)
         self.cmd('create', self.repository_location + '::test-2', src_dir)
-        output = self.cmd('list', '--prefix=test-', self.repository_location)
+        output = self.cmd('list', '--glob-archives=test-*', self.repository_location)
         self.assert_in('test-1', output)
         self.assert_in('test-2', output)
         self.assert_not_in('something-else', output)
@@ -2672,13 +2672,13 @@ class ArchiverTestCase(ArchiverTestCaseBase):
             assert sorted(os.listdir(os.path.join(mountpoint))) == ['arch11', 'arch12']
         with self.fuse_mount(self.repository_location, mountpoint, '--last=2', '--sort=name'):
             assert sorted(os.listdir(os.path.join(mountpoint))) == ['arch21', 'arch22']
-        with self.fuse_mount(self.repository_location, mountpoint, '--prefix=arch1'):
+        with self.fuse_mount(self.repository_location, mountpoint, '--glob-archives=arch1*'):
             assert sorted(os.listdir(os.path.join(mountpoint))) == ['arch11', 'arch12']
-        with self.fuse_mount(self.repository_location, mountpoint, '--prefix=arch2'):
+        with self.fuse_mount(self.repository_location, mountpoint, '--glob-archives=arch2*'):
             assert sorted(os.listdir(os.path.join(mountpoint))) == ['arch21', 'arch22']
-        with self.fuse_mount(self.repository_location, mountpoint, '--prefix=arch'):
+        with self.fuse_mount(self.repository_location, mountpoint, '--glob-archives=arch*'):
             assert sorted(os.listdir(os.path.join(mountpoint))) == ['arch11', 'arch12', 'arch21', 'arch22']
-        with self.fuse_mount(self.repository_location, mountpoint, '--prefix=nope'):
+        with self.fuse_mount(self.repository_location, mountpoint, '--glob-archives=nope*'):
             assert sorted(os.listdir(os.path.join(mountpoint))) == []
 
     @unittest.skipUnless(llfuse, 'llfuse not installed')
@@ -3650,7 +3650,7 @@ class ArchiverCheckTestCase(ArchiverTestCaseBase):
         output = self.cmd('check', '-v', '--archives-only', self.repository_location, exit_code=0)
         self.assert_not_in('Starting repository check', output)
         self.assert_in('Starting archive consistency check', output)
-        output = self.cmd('check', '-v', '--archives-only', '--prefix=archive2', self.repository_location, exit_code=0)
+        output = self.cmd('check', '-v', '--archives-only', '--glob-archives=archive2', self.repository_location, exit_code=0)
         self.assert_not_in('archive1', output)
         output = self.cmd('check', '-v', '--archives-only', '--first=1', self.repository_location, exit_code=0)
         self.assert_in('archive1', output)