1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2024-12-09 09:46:52 +00:00

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.
This commit is contained in:
Daniel Rudolf 2024-11-08 01:50:45 +01:00
parent 2dffc60507
commit 38ba3d8c4d
8 changed files with 30 additions and 25 deletions

View file

@ -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:

View file

@ -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:

View file

@ -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

View file

@ -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

View file

@ -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(

View file

@ -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``.

View file

@ -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``.

View file

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