Merge pull request #8525 from PhrozenByte/docs-undelete

Update docs to better incorporate new undelete command

docs/changes.rst

@@ -97,6 +97,8 @@ Compatibility notes:
   - removed --save-space option (does not change behaviour)
 - removed --bypass-lock option
 - removed borg config command (only worked locally anyway)
+- compact command now requires access to the borg key if the repo is encrypted
+  or authenticated
 - using --list together with --progress is now disallowed (except with --log-json), #7219
 - the --glob-archives option was renamed to --match-archives (the short option
   name -a is unchanged) and extended to support different pattern styles:

src/borg/archive.py

@@ -1867,7 +1867,9 @@ def valid_archive(obj):
                 if self.manifest.archives.exists_id(archive_id, deleted=False):
                     logger.debug(f"We already have an archives directory entry for {name} {archive_id_hex}.")
                 elif self.manifest.archives.exists_id(archive_id, deleted=True):
-                    logger.debug(f"We already have a deleted archives directory entry for {name} {archive_id_hex}.")
+                    logger.debug(
+                        f"We already have a soft-deleted archives directory entry for {name} {archive_id_hex}."
+                    )
                 else:
                     self.error_found = True
                     if self.repair:

src/borg/archiver/_common.py

@@ -460,7 +460,7 @@ def define_archive_filters_group(
 
     if deleted:
         filters_group.add_argument(
-            "--deleted", dest="deleted", action="store_true", help="consider only deleted archives."
+            "--deleted", dest="deleted", action="store_true", help="consider only soft-deleted archives."
         )
 
     return filters_group

src/borg/archiver/check_cmd.py

@@ -126,8 +126,8 @@ def build_parser_check(self, subparsers, common_parser, mid_common_parser):
 
         The ``--find-lost-archives`` option will also scan the whole repository, but
         tells Borg to search for lost archive metadata. If Borg encounters any archive
-        metadata that doesn't match with an archive directory entry, it means that an
-        entry was lost.
+        metadata that doesn't match with an archive directory entry (including
+        soft-deleted archives), it means that an entry was lost.
         Unless ``borg compact`` is called, these archives can be fully restored with
         ``--repair``. Please note that ``--find-lost-archives`` must read a lot of
         data from the repository and is thus very time consuming. You can not use

src/borg/archiver/compact_cmd.py

@@ -127,7 +127,7 @@ def report_and_delete(self):
             logger.warning(f"{len(self.reappeared_chunks)} previously missing objects re-appeared!" + run_repair)
             set_ec(EXIT_WARNING)
 
-        logger.info("Cleaning archives directory from deleted archives...")
+        logger.info("Cleaning archives directory from soft-deleted archives...")
         archive_infos = self.manifest.archives.list(sort_by=["ts"], deleted=True)
         for archive_info in archive_infos:
             name, id, hex_id = archive_info.name, archive_info.id, bin_to_hex(archive_info.id)
@@ -176,35 +176,33 @@ def build_parser_compact(self, subparsers, common_parser, mid_common_parser):
             Free repository space by deleting unused chunks.
 
             borg compact analyzes all existing archives to find out which repository
-            objects are actually used (referenced). It then removes all unused objects
-            to free repository space.
+            objects are actually used (referenced). It then deletes all unused objects
+            from the repository to free space.
 
             Unused objects may result from:
 
             - borg delete or prune usage
-            - interrupted backups (maybe retry the backup first before running compact!)
+            - interrupted backups (maybe retry the backup first before running compact)
             - backup of source files that had an I/O error in the middle of their contents
-              and that were skipped due to this.
-            - corruption of the repository (e.g. the archives directory having lost entries)
+              and that were skipped due to this
+            - corruption of the repository (e.g. the archives directory having lost
+              entries, see notes below)
 
             You usually don't want to run ``borg compact`` after every write operation, but
             either regularly (e.g. once a month, possibly together with ``borg check``) or
             when disk space needs to be freed.
 
             **Important:**
 
-            After compacting it is not possible anymore to use ``borg undelete`` to recover
-            previously deleted archives.
+            After compacting it is no longer possible to use ``borg undelete`` to recover
+            previously soft-deleted archives.
 
             ``borg compact`` might also delete data from archives that were "lost" due to
             archives directory corruption. Such archives could potentially be restored with
-            ``borg check --find-lost-archives [--repair]``, which is slow and thus you
-            maybe usually don't want to do that unless there are signs of lost archives
-            (e.g. when seeing fatal errors when creating backups or when archives are
-            missing in ``borg list``).
-
-            Differently than borg 1.x, borg2's compact needs the borg key if the repo is
-            encrypted.
+            ``borg check --find-lost-archives [--repair]``, which is slow. You therefore
+            might not want to do that unless there are signs of lost archives (e.g. when
+            seeing fatal errors when creating backups or when archives are missing in
+            ``borg repo-list``).
             """
         )
         subparser = subparsers.add_parser(

src/borg/archiver/delete_cmd.py

@@ -62,11 +62,12 @@ def build_parser_delete(self, subparsers, common_parser, mid_common_parser):
 
         delete_epilog = process_epilog(
             """
-        This command deletes archives from the repository.
+        This command soft-deletes archives from the repository.
 
         Important:
 
-        - Repository disk space is **not** freed until you run ``borg compact``.
+        - The delete command will only mark archives for deletion ("soft-deletion"),
+          repository disk space is **not** freed until you run ``borg compact``.
         - You can use ``borg undelete`` to undelete archives, but only until
           you run ``borg compact``.
 

src/borg/archiver/prune_cmd.py

@@ -212,12 +212,13 @@ def build_parser_prune(self, subparsers, common_parser, mid_common_parser):
 
         prune_epilog = process_epilog(
             """
-        The prune command prunes a repository by deleting all archives not matching
-        any of the specified retention options.
+        The prune command prunes a repository by soft-deleting all archives not
+        matching any of the specified retention options.
 
         Important:
 
-        - Repository disk space is **not** freed until you run ``borg compact``.
+        - The prune command will only mark archives for deletion ("soft-deletion"),
+          repository disk space is **not** freed until you run ``borg compact``.
         - You can use ``borg undelete`` to undelete archives, but only until
           you run ``borg compact``.
 

src/borg/archiver/undelete_cmd.py

@@ -61,7 +61,8 @@ def build_parser_undelete(self, subparsers, common_parser, mid_common_parser):
 
         Important: Undeleting archives is only possible before compacting.
         Once ``borg compact`` has run, all disk space occupied only by the
-        deleted archives will be freed and undelete is not possible anymore.
+        soft-deleted archives will be freed and undelete is not possible
+        anymore.
 
         When in doubt, use ``--dry-run --list`` to see what would be undeleted.