From 38ba3d8c4d690917871bd4dbd8e357329cc5f980 Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Fri, 8 Nov 2024 01:50:45 +0100 Subject: [PATCH] Update docs to better incorporate new undelete command Follow-up to #8515 Refer to https://github.com/borgbackup/borg/pull/8515#pullrequestreview-2417746853 for details. --- docs/changes.rst | 2 ++ src/borg/archive.py | 4 +++- src/borg/archiver/_common.py | 2 +- src/borg/archiver/check_cmd.py | 4 ++-- src/borg/archiver/compact_cmd.py | 28 +++++++++++++--------------- src/borg/archiver/delete_cmd.py | 5 +++-- src/borg/archiver/prune_cmd.py | 7 ++++--- src/borg/archiver/undelete_cmd.py | 3 ++- 8 files changed, 30 insertions(+), 25 deletions(-) diff --git a/docs/changes.rst b/docs/changes.rst index 7f23bfc88..049274c51 100644 --- a/docs/changes.rst +++ b/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: diff --git a/src/borg/archive.py b/src/borg/archive.py index c07cec08c..0887741c5 100644 --- a/src/borg/archive.py +++ b/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: diff --git a/src/borg/archiver/_common.py b/src/borg/archiver/_common.py index 068a1fba5..0f59549ed 100644 --- a/src/borg/archiver/_common.py +++ b/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 diff --git a/src/borg/archiver/check_cmd.py b/src/borg/archiver/check_cmd.py index a5b5bf09f..0bfda9b78 100644 --- a/src/borg/archiver/check_cmd.py +++ b/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 diff --git a/src/borg/archiver/compact_cmd.py b/src/borg/archiver/compact_cmd.py index 310296fdb..2ead37488 100644 --- a/src/borg/archiver/compact_cmd.py +++ b/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,16 +176,17 @@ 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 @@ -193,18 +194,15 @@ def build_parser_compact(self, subparsers, common_parser, mid_common_parser): **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( diff --git a/src/borg/archiver/delete_cmd.py b/src/borg/archiver/delete_cmd.py index ee411428b..36e412e53 100644 --- a/src/borg/archiver/delete_cmd.py +++ b/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``. diff --git a/src/borg/archiver/prune_cmd.py b/src/borg/archiver/prune_cmd.py index 654d89fcc..435f084e4 100644 --- a/src/borg/archiver/prune_cmd.py +++ b/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``. diff --git a/src/borg/archiver/undelete_cmd.py b/src/borg/archiver/undelete_cmd.py index 31e38ca51..a4008cdeb 100644 --- a/src/borg/archiver/undelete_cmd.py +++ b/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.