From e8a6421ebfea1c67c0f0b73430390c14b72145f8 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 16 Nov 2024 20:08:19 +0100 Subject: [PATCH 1/2] b14 release date --- docs/changes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/changes.rst b/docs/changes.rst index a9958e180..abe33af5a 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -144,7 +144,7 @@ Compatibility notes: Change Log 2.x ============== -Version 2.0.0b14 (2024-11-xx) +Version 2.0.0b14 (2024-11-17) ----------------------------- Please note: From 37077a55e717fef8bac18473edc125036099488a Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 16 Nov 2024 20:14:16 +0100 Subject: [PATCH 2/2] build_usage build_man --- docs/man/borg-analyze.1 | 2 +- docs/man/borg-benchmark-cpu.1 | 2 +- docs/man/borg-benchmark-crud.1 | 2 +- docs/man/borg-benchmark.1 | 2 +- docs/man/borg-break-lock.1 | 2 +- docs/man/borg-check.1 | 35 +++++---- docs/man/borg-common.1 | 2 +- docs/man/borg-compact.1 | 39 ++++++++-- docs/man/borg-compression.1 | 5 +- docs/man/borg-create.1 | 2 +- docs/man/borg-delete.1 | 13 +++- docs/man/borg-diff.1 | 2 +- docs/man/borg-export-tar.1 | 2 +- docs/man/borg-extract.1 | 2 +- docs/man/borg-import-tar.1 | 2 +- docs/man/borg-info.1 | 2 +- docs/man/borg-key-change-location.1 | 2 +- docs/man/borg-key-change-passphrase.1 | 2 +- docs/man/borg-key-export.1 | 2 +- docs/man/borg-key-import.1 | 2 +- docs/man/borg-key.1 | 2 +- docs/man/borg-list.1 | 2 +- docs/man/borg-match-archives.1 | 2 +- docs/man/borg-mount.1 | 6 +- docs/man/borg-patterns.1 | 2 +- docs/man/borg-placeholders.1 | 2 +- docs/man/borg-prune.1 | 16 +++- docs/man/borg-recreate.1 | 2 +- docs/man/borg-rename.1 | 2 +- docs/man/borg-repo-compress.1 | 2 +- docs/man/borg-repo-create.1 | 2 +- docs/man/borg-repo-delete.1 | 2 +- docs/man/borg-repo-info.1 | 2 +- docs/man/borg-repo-list.1 | 5 +- docs/man/borg-repo-space.1 | 2 +- docs/man/borg-serve.1 | 2 +- docs/man/borg-tag.1 | 2 +- docs/man/borg-transfer.1 | 2 +- docs/man/borg-umount.1 | 2 +- docs/man/borg-undelete.1 | 101 ++++++++++++++++++++++++++ docs/man/borg-version.1 | 2 +- docs/man/borg-with-lock.1 | 2 +- docs/man/borg.1 | 2 +- docs/man/borgfs.1 | 2 +- docs/usage/check.rst.inc | 33 ++++++--- docs/usage/compact.rst.inc | 32 ++++++-- docs/usage/delete.rst.inc | 10 ++- docs/usage/help.rst.inc | 3 +- docs/usage/mount.rst.inc | 4 +- docs/usage/prune.rst.inc | 11 ++- docs/usage/repo-list.rst.inc | 3 + docs/usage/undelete.rst | 1 + docs/usage/undelete.rst.inc | 96 ++++++++++++++++++++++++ 53 files changed, 391 insertions(+), 94 deletions(-) create mode 100644 docs/man/borg-undelete.1 create mode 100644 docs/usage/undelete.rst create mode 100644 docs/usage/undelete.rst.inc diff --git a/docs/man/borg-analyze.1 b/docs/man/borg-analyze.1 index b9ced8dbf..6a389893b 100644 --- a/docs/man/borg-analyze.1 +++ b/docs/man/borg-analyze.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-ANALYZE" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-ANALYZE" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-analyze \- Analyze archives .SH SYNOPSIS diff --git a/docs/man/borg-benchmark-cpu.1 b/docs/man/borg-benchmark-cpu.1 index 7b6e39ebf..d1efc1dc8 100644 --- a/docs/man/borg-benchmark-cpu.1 +++ b/docs/man/borg-benchmark-cpu.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BENCHMARK-CPU" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-BENCHMARK-CPU" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-benchmark-cpu \- Benchmark CPU bound operations. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 6556c4970..7d5b8fd24 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BENCHMARK-CRUD" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-BENCHMARK-CRUD" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index 1345b1cfb..be672da71 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BENCHMARK" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-BENCHMARK" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-benchmark \- benchmark command .SH SYNOPSIS diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index 2e8f29eae..b7457dd2f 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BREAK-LOCK" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-BREAK-LOCK" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. .SH SYNOPSIS diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 57c1fb479..24d763ea7 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CHECK" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-CHECK" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency .SH SYNOPSIS @@ -51,12 +51,14 @@ Checking consistency and correctness of the archive metadata and optionally archive data (requires \fB\-\-verify\-data\fP). This includes ensuring that the repository manifest exists, the archive metadata chunk is present, and that all chunks referencing files (items) in the archive exist. This requires -reading archive and file metadata, but not data. To cryptographically verify -the file (content) data integrity pass \fB\-\-verify\-data\fP, but keep in mind -that this requires reading all data and is hence very time consuming. When -checking archives of a remote repository, archive checks run on the client -machine because they require decrypting data and therefore the encryption -key. +reading archive and file metadata, but not data. To scan for archives whose +entries were lost from the archive directory, pass \fB\-\-find\-lost\-archives\fP\&. +It requires reading all data and is hence very time consuming. +To additionally cryptographically verify the file (content) data integrity, +pass \fB\-\-verify\-data\fP, which is even more time consuming. +.sp +When checking archives of a remote repository, archive checks run on the client +machine because they require decrypting data and therefore the encryption key. .UNINDENT .sp Both steps can also be run independently. Pass \fB\-\-repository\-only\fP to run the @@ -88,6 +90,15 @@ cryptographic verification and hence very time consuming, but will detect any accidental and malicious corruption. Tamper\-resistance is only guaranteed for encrypted repositories against attackers without access to the keys. You can not use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&. +.sp +The \fB\-\-find\-lost\-archives\fP option will also scan the whole repository, but +tells Borg to search for lost archive metadata. If Borg encounters any archive +metadata that doesn\(aqt match with an archive directory entry (including +soft\-deleted archives), it means that an entry was lost. +Unless \fBborg compact\fP is called, these archives can be fully restored with +\fB\-\-repair\fP\&. Please note that \fB\-\-find\-lost\-archives\fP must read a lot of +data from the repository and is thus very time consuming. You can not use +\fB\-\-find\-lost\-archives\fP with \fB\-\-repository\-only\fP\&. .SS About repair mode .sp The check command is a readonly task by default. If any corruption is found, @@ -150,10 +161,8 @@ chunks of a \(dqzero\-patched\(dq file reappear, this effectively \(dqheals\(dq Consequently, if lost chunks were repaired earlier, it is advised to run \fB\-\-repair\fP a second time after creating some new backups. .sp -If \fB\-\-repair \-\-undelete\-archives\fP is given, Borg will scan the repository -for archive metadata and if it finds some where no corresponding archives -directory entry exists, it will create the entries. This is basically undoing -\fBborg delete archive\fP or \fBborg prune ...\fP commands and only possible before +If \fB\-\-repair \-\-find\-lost\-archives\fP is given, previously lost entries will +be recreated in the archive directory. This is only possible before \fBborg compact\fP would remove the archives\(aq data completely. .SH OPTIONS .sp @@ -173,8 +182,8 @@ perform cryptographic archive data integrity verification (conflicts with \fB\-\ .B \-\-repair attempt to repair any inconsistencies found .TP -.B \-\-undelete\-archives -attempt to undelete archives (use with \-\-repair) +.B \-\-find\-lost\-archives +attempt to find lost archives .TP .BI \-\-max\-duration \ SECONDS do only a partial repo check for max. SECONDS seconds (Default: unlimited) diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index a6d41f363..4d00a2b3e 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMMON" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-COMMON" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands .SH SYNOPSIS diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index 553388de5..47f84d5f7 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMPACT" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-COMPACT" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-compact \- Collect garbage in repository .SH SYNOPSIS @@ -37,12 +37,39 @@ borg [common options] compact [options] .sp Free repository space by deleting unused chunks. .sp -borg compact analyzes all existing archives to find out which chunks are -actually used. There might be unused chunks resulting from borg delete or prune, -which can be removed to free space in the repository. +borg compact analyzes all existing archives to find out which repository +objects are actually used (referenced). It then deletes all unused objects +from the repository to free space. .sp -Differently than borg 1.x, borg2\(aqs compact needs the borg key if the repo is -encrypted. +Unused objects may result from: +.INDENT 0.0 +.IP \(bu 2 +borg delete or prune usage +.IP \(bu 2 +interrupted backups (maybe retry the backup first before running compact) +.IP \(bu 2 +backup of source files that had an I/O error in the middle of their contents +and that were skipped due to this +.IP \(bu 2 +corruption of the repository (e.g. the archives directory having lost +entries, see notes below) +.UNINDENT +.sp +You usually don\(aqt want to run \fBborg compact\fP after every write operation, but +either regularly (e.g. once a month, possibly together with \fBborg check\fP) or +when disk space needs to be freed. +.sp +\fBImportant:\fP +.sp +After compacting it is no longer possible to use \fBborg undelete\fP to recover +previously soft\-deleted archives. +.sp +\fBborg compact\fP might also delete data from archives that were \(dqlost\(dq due to +archives directory corruption. Such archives could potentially be restored with +\fBborg check \-\-find\-lost\-archives [\-\-repair]\fP, 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 +\fBborg repo\-list\fP). .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index 7d028bc70..a8e161362 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMPRESSION" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-COMPRESSION" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression .SH DESCRIPTION @@ -77,7 +77,8 @@ Use a built\-in heuristic to decide per chunk whether to compress or not. The heuristic tries with lz4 whether the data is compressible. For incompressible data, it will not use compression (uses \(dqnone\(dq). For compressible data, it uses the given C[,L] compression \- with C[,L] -being any valid compression specifier. +being any valid compression specifier. This can be helpful for media files +which often cannot be compressed much more. .TP .B obfuscate,SPEC,C[,L] Use compressed\-size obfuscation to make fingerprinting attacks based on diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index c546f5ddf..0186ad09f 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CREATE" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-CREATE" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-create \- Create new archive .SH SYNOPSIS diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index bcde371f5..6a2127e9e 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-DELETE" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-DELETE" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-delete \- Delete archives .SH SYNOPSIS @@ -35,10 +35,17 @@ borg-delete \- Delete archives borg [common options] delete [options] [NAME] .SH DESCRIPTION .sp -This command deletes archives from the repository. +This command soft\-deletes archives from the repository. .sp -Important: When deleting archives, repository disk space is \fBnot\fP freed until +Important: +.INDENT 0.0 +.IP \(bu 2 +The delete command will only mark archives for deletion (\(dqsoft\-deletion\(dq), +repository disk space is \fBnot\fP freed until you run \fBborg compact\fP\&. +.IP \(bu 2 +You can use \fBborg undelete\fP to undelete archives, but only until you run \fBborg compact\fP\&. +.UNINDENT .sp When in doubt, use \fB\-\-dry\-run \-\-list\fP to see what would be deleted. .sp diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index 429a4421b..87daea01c 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-DIFF" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-DIFF" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives .SH SYNOPSIS diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 0dc9436b0..776f18c93 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-EXPORT-TAR" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-EXPORT-TAR" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball .SH SYNOPSIS diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index 1082bfb52..3e8c17766 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-EXTRACT" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-EXTRACT" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents .SH SYNOPSIS diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1 index 56b3958b8..c2d21ce9d 100644 --- a/docs/man/borg-import-tar.1 +++ b/docs/man/borg-import-tar.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-IMPORT-TAR" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-IMPORT-TAR" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-import-tar \- Create a backup archive from a tarball .SH SYNOPSIS diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index 6c147ea55..358d2ef6c 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-INFO" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-INFO" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used .SH SYNOPSIS diff --git a/docs/man/borg-key-change-location.1 b/docs/man/borg-key-change-location.1 index 113d7f9ba..7aa8a86b8 100644 --- a/docs/man/borg-key-change-location.1 +++ b/docs/man/borg-key-change-location.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-CHANGE-LOCATION" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-KEY-CHANGE-LOCATION" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-key-change-location \- Change repository key location .SH SYNOPSIS diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index e9b38c427..7c2033e48 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase .SH SYNOPSIS diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 1c34ec6a7..85b5e1e7c 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-EXPORT" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-KEY-EXPORT" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-key-export \- Export the repository key for backup .SH SYNOPSIS diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index bdefc1b76..df9b652ab 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-IMPORT" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-KEY-IMPORT" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup .SH SYNOPSIS diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 07e46cdfc..1737e216a 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-KEY" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-key \- Manage a keyfile or repokey of a repository .SH SYNOPSIS diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index d191eb041..5c25fc82c 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-LIST" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-LIST" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-list \- List archive contents .SH SYNOPSIS diff --git a/docs/man/borg-match-archives.1 b/docs/man/borg-match-archives.1 index 88f2fe4b8..744bd0b3d 100644 --- a/docs/man/borg-match-archives.1 +++ b/docs/man/borg-match-archives.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-MATCH-ARCHIVES" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-MATCH-ARCHIVES" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-match-archives \- Details regarding match-archives .SH DESCRIPTION diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index f796a2d68..9296ddf1e 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-MOUNT" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-MOUNT" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS @@ -109,8 +109,8 @@ When the daemonized process receives a signal or crashes, it does not unmount. Unmounting in these cases could cause an active rsync or similar process to delete data unintentionally. .sp -When running in the foreground ^C/SIGINT unmounts cleanly, but other -signals or crashes do not. +When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem, +but other signals or crashes do not. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 77887761c..e99bf8021 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PATTERNS" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-PATTERNS" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns .SH DESCRIPTION diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index aa5331b93..2c1b15505 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PLACEHOLDERS" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-PLACEHOLDERS" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders .SH DESCRIPTION diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index 4a56af6f6..76883876a 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PRUNE" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-PRUNE" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules .SH SYNOPSIS @@ -35,10 +35,18 @@ borg-prune \- Prune repository archives according to specified rules borg [common options] prune [options] [NAME] .SH DESCRIPTION .sp -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. .sp -Important: Repository disk space is \fBnot\fP freed until you run \fBborg compact\fP\&. +Important: +.INDENT 0.0 +.IP \(bu 2 +The prune command will only mark archives for deletion (\(dqsoft\-deletion\(dq), +repository disk space is \fBnot\fP freed until you run \fBborg compact\fP\&. +.IP \(bu 2 +You can use \fBborg undelete\fP to undelete archives, but only until +you run \fBborg compact\fP\&. +.UNINDENT .sp This command is normally used by automated backup scripts wanting to keep a certain number of historic backups. This retention policy is commonly referred to as diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 443ba1b28..b97c20257 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RECREATE" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-RECREATE" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives .SH SYNOPSIS diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index a262bfdff..1e74e6a6e 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RENAME" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-RENAME" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-rename \- Rename an existing archive .SH SYNOPSIS diff --git a/docs/man/borg-repo-compress.1 b/docs/man/borg-repo-compress.1 index 2efc64ea8..47bec4fd1 100644 --- a/docs/man/borg-repo-compress.1 +++ b/docs/man/borg-repo-compress.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-REPO-COMPRESS" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-REPO-COMPRESS" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-repo-compress \- Repository (re-)compression .SH SYNOPSIS diff --git a/docs/man/borg-repo-create.1 b/docs/man/borg-repo-create.1 index e50baad5d..2a0db24dd 100644 --- a/docs/man/borg-repo-create.1 +++ b/docs/man/borg-repo-create.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-REPO-CREATE" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-REPO-CREATE" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-repo-create \- Create a new, empty repository .SH SYNOPSIS diff --git a/docs/man/borg-repo-delete.1 b/docs/man/borg-repo-delete.1 index ada2f73dc..6949c3819 100644 --- a/docs/man/borg-repo-delete.1 +++ b/docs/man/borg-repo-delete.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-REPO-DELETE" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-REPO-DELETE" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-repo-delete \- Delete a repository .SH SYNOPSIS diff --git a/docs/man/borg-repo-info.1 b/docs/man/borg-repo-info.1 index db89ffb0a..c4f2dbb3a 100644 --- a/docs/man/borg-repo-info.1 +++ b/docs/man/borg-repo-info.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-REPO-INFO" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-REPO-INFO" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-repo-info \- Show repository infos .SH SYNOPSIS diff --git a/docs/man/borg-repo-list.1 b/docs/man/borg-repo-list.1 index 005818506..569567238 100644 --- a/docs/man/borg-repo-list.1 +++ b/docs/man/borg-repo-list.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-REPO-LIST" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-REPO-LIST" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-repo-list \- List the archives contained in a repository .SH SYNOPSIS @@ -77,6 +77,9 @@ consider archives older than (now \- TIMESPAN), e.g. 7d or 12m. .TP .BI \-\-newer \ TIMESPAN consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. +.TP +.B \-\-deleted +consider only soft\-deleted archives. .UNINDENT .SH EXAMPLES .INDENT 0.0 diff --git a/docs/man/borg-repo-space.1 b/docs/man/borg-repo-space.1 index 2b881b0dc..6907fb4c5 100644 --- a/docs/man/borg-repo-space.1 +++ b/docs/man/borg-repo-space.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-REPO-SPACE" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-REPO-SPACE" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-repo-space \- Manage reserved space in repository .SH SYNOPSIS diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index a33fd7d1e..598562c36 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-SERVE" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-SERVE" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. .SH SYNOPSIS diff --git a/docs/man/borg-tag.1 b/docs/man/borg-tag.1 index b946761ff..d7bc24890 100644 --- a/docs/man/borg-tag.1 +++ b/docs/man/borg-tag.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-TAG" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-TAG" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-tag \- Manage tags .SH SYNOPSIS diff --git a/docs/man/borg-transfer.1 b/docs/man/borg-transfer.1 index f36a22259..5a97b0730 100644 --- a/docs/man/borg-transfer.1 +++ b/docs/man/borg-transfer.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-TRANSFER" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-TRANSFER" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-transfer \- archives transfer from other repository, optionally upgrade data format .SH SYNOPSIS diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index d35dd8108..3fba13d8d 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-UMOUNT" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-UMOUNT" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-umount \- un-mount the FUSE filesystem .SH SYNOPSIS diff --git a/docs/man/borg-undelete.1 b/docs/man/borg-undelete.1 new file mode 100644 index 000000000..4d0c2abad --- /dev/null +++ b/docs/man/borg-undelete.1 @@ -0,0 +1,101 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "BORG-UNDELETE" 1 "2024-11-16" "" "borg backup tool" +.SH NAME +borg-undelete \- Undelete archives +.SH SYNOPSIS +.sp +borg [common options] undelete [options] [NAME] +.SH DESCRIPTION +.sp +This command undeletes archives in the repository. +.sp +Important: Undeleting archives is only possible before compacting. +Once \fBborg compact\fP has run, all disk space occupied only by the +soft\-deleted archives will be freed and undelete is not possible +anymore. +.sp +When in doubt, use \fB\-\-dry\-run \-\-list\fP to see what would be undeleted. +.sp +You can undelete multiple archives by specifying a matching pattern, +using the \fB\-\-match\-archives PATTERN\fP option (for more info on these patterns, +see \fIborg_patterns\fP). +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS arguments +.INDENT 0.0 +.TP +.B NAME +specify the archive name +.UNINDENT +.SS optional arguments +.INDENT 0.0 +.TP +.B \-n\fP,\fB \-\-dry\-run +do not change repository +.TP +.B \-\-list +output verbose list of archives +.UNINDENT +.SS Archive filters +.INDENT 0.0 +.TP +.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN +only consider archives matching all patterns. see \(dqborg help match\-archives\(dq. +.TP +.BI \-\-sort\-by \ KEYS +Comma\-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp +.TP +.BI \-\-first \ N +consider first N archives after other filters were applied +.TP +.BI \-\-last \ N +consider last N archives after other filters were applied +.TP +.BI \-\-oldest \ TIMESPAN +consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newest \ TIMESPAN +consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-older \ TIMESPAN +consider archives older than (now \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newer \ TIMESPAN +consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-version.1 b/docs/man/borg-version.1 index b056387b7..3302c9276 100644 --- a/docs/man/borg-version.1 +++ b/docs/man/borg-version.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-VERSION" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-VERSION" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-version \- Display the borg client / borg server version .SH SYNOPSIS diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index 3faa12e80..fb607fed2 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-WITH-LOCK" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG-WITH-LOCK" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg-with-lock \- run a user specified command with the repository lock held .SH SYNOPSIS diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 98df6cba3..4d235eae7 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG" 1 "2024-10-31" "" "borg backup tool" +.TH "BORG" 1 "2024-11-16" "" "borg backup tool" .SH NAME borg \- deduplicating and encrypting backup tool .SH SYNOPSIS diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index 0895326e3..4d1f34c6a 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORGFS" 1 "2024-10-31" "" "borg backup tool" +.TH "BORGFS" 1 "2024-11-16" "" "borg backup tool" .SH NAME borgfs \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc index cb48a0dc3..a76fb58f9 100644 --- a/docs/usage/check.rst.inc +++ b/docs/usage/check.rst.inc @@ -23,7 +23,7 @@ borg check +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ | | ``--repair`` | attempt to repair any inconsistencies found | +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ - | | ``--undelete-archives`` | attempt to undelete archives (use with --repair) | + | | ``--find-lost-archives`` | attempt to find lost archives | +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ | | ``--max-duration SECONDS`` | do only a partial repo check for max. SECONDS seconds (Default: unlimited) | +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ @@ -67,7 +67,7 @@ borg check --archives-only only perform archives checks --verify-data perform cryptographic archive data integrity verification (conflicts with ``--repository-only``) --repair attempt to repair any inconsistencies found - --undelete-archives attempt to undelete archives (use with --repair) + --find-lost-archives attempt to find lost archives --max-duration SECONDS do only a partial repo check for max. SECONDS seconds (Default: unlimited) @@ -103,12 +103,14 @@ It consists of two major steps: archive data (requires ``--verify-data``). This includes ensuring that the repository manifest exists, the archive metadata chunk is present, and that all chunks referencing files (items) in the archive exist. This requires - reading archive and file metadata, but not data. To cryptographically verify - the file (content) data integrity pass ``--verify-data``, but keep in mind - that this requires reading all data and is hence very time consuming. When - checking archives of a remote repository, archive checks run on the client - machine because they require decrypting data and therefore the encryption - key. + reading archive and file metadata, but not data. To scan for archives whose + entries were lost from the archive directory, pass ``--find-lost-archives``. + It requires reading all data and is hence very time consuming. + To additionally cryptographically verify the file (content) data integrity, + pass ``--verify-data``, which is even more time consuming. + + When checking archives of a remote repository, archive checks run on the client + machine because they require decrypting data and therefore the encryption key. Both steps can also be run independently. Pass ``--repository-only`` to run the repository checks only, or pass ``--archives-only`` to run the archive checks @@ -140,6 +142,15 @@ accidental and malicious corruption. Tamper-resistance is only guaranteed for encrypted repositories against attackers without access to the keys. You can not use ``--verify-data`` with ``--repository-only``. +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 (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 +``--find-lost-archives`` with ``--repository-only``. + About repair mode +++++++++++++++++ @@ -198,8 +209,6 @@ chunks of a "zero-patched" file reappear, this effectively "heals" the file. Consequently, if lost chunks were repaired earlier, it is advised to run ``--repair`` a second time after creating some new backups. -If ``--repair --undelete-archives`` is given, Borg will scan the repository -for archive metadata and if it finds some where no corresponding archives -directory entry exists, it will create the entries. This is basically undoing -``borg delete archive`` or ``borg prune ...`` commands and only possible before +If ``--repair --find-lost-archives`` is given, previously lost entries will +be recreated in the archive directory. This is only possible before ``borg compact`` would remove the archives' data completely. \ No newline at end of file diff --git a/docs/usage/compact.rst.inc b/docs/usage/compact.rst.inc index 8fad820d0..dcb3bafa8 100644 --- a/docs/usage/compact.rst.inc +++ b/docs/usage/compact.rst.inc @@ -38,9 +38,31 @@ Description Free repository space by deleting unused chunks. -borg compact analyzes all existing archives to find out which chunks are -actually used. There might be unused chunks resulting from borg delete or prune, -which can be removed to free space in the repository. +borg compact analyzes all existing archives to find out which repository +objects are actually used (referenced). It then deletes all unused objects +from the repository to free space. -Differently than borg 1.x, borg2's compact needs the borg key if the repo is -encrypted. \ No newline at end of file +Unused objects may result from: + +- borg delete or prune usage +- 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, 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 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. 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``). \ No newline at end of file diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc index bfdb61fd5..449ab3a4a 100644 --- a/docs/usage/delete.rst.inc +++ b/docs/usage/delete.rst.inc @@ -82,10 +82,14 @@ borg delete Description ~~~~~~~~~~~ -This command deletes archives from the repository. +This command soft-deletes archives from the repository. -Important: When deleting archives, repository disk space is **not** freed until -you run ``borg compact``. +Important: + +- 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``. When in doubt, use ``--dry-run --list`` to see what would be deleted. diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 59b2e303a..6570af524 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -425,7 +425,8 @@ auto,C[,L] The heuristic tries with lz4 whether the data is compressible. For incompressible data, it will not use compression (uses "none"). For compressible data, it uses the given C[,L] compression - with C[,L] - being any valid compression specifier. + being any valid compression specifier. This can be helpful for media files + which often cannot be compressed much more. obfuscate,SPEC,C[,L] Use compressed-size obfuscation to make fingerprinting attacks based on diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc index 9ce61901b..3f9dde600 100644 --- a/docs/usage/mount.rst.inc +++ b/docs/usage/mount.rst.inc @@ -175,5 +175,5 @@ When the daemonized process receives a signal or crashes, it does not unmount. Unmounting in these cases could cause an active rsync or similar process to delete data unintentionally. -When running in the foreground ^C/SIGINT unmounts cleanly, but other -signals or crashes do not. \ No newline at end of file +When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem, +but other signals or crashes do not. \ No newline at end of file diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index 9968c7e99..e21a7002e 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -115,10 +115,15 @@ borg prune Description ~~~~~~~~~~~ -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``. +Important: + +- 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``. This command is normally used by automated backup scripts wanting to keep a certain number of historic backups. This retention policy is commonly referred to as diff --git a/docs/usage/repo-list.rst.inc b/docs/usage/repo-list.rst.inc index d6ab65d57..e891a99ef 100644 --- a/docs/usage/repo-list.rst.inc +++ b/docs/usage/repo-list.rst.inc @@ -43,6 +43,8 @@ borg repo-list +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--deleted`` | consider only soft-deleted archives. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -74,6 +76,7 @@ borg repo-list --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d or 12m. --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. + --deleted consider only soft-deleted archives. Description diff --git a/docs/usage/undelete.rst b/docs/usage/undelete.rst new file mode 100644 index 000000000..c289127e2 --- /dev/null +++ b/docs/usage/undelete.rst @@ -0,0 +1 @@ +.. include:: undelete.rst.inc diff --git a/docs/usage/undelete.rst.inc b/docs/usage/undelete.rst.inc new file mode 100644 index 000000000..ed8bd5db0 --- /dev/null +++ b/docs/usage/undelete.rst.inc @@ -0,0 +1,96 @@ +.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! + +.. _borg_undelete: + +borg undelete +------------- +.. code-block:: none + + borg [common options] undelete [options] [NAME] + +.. only:: html + + .. class:: borg-options-table + + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``NAME`` | specify the archive name | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | **optional arguments** | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``-n``, ``--dry-run`` | do not change repository | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``--list`` | output verbose list of archives | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. see "borg help match-archives". | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``--first N`` | consider first N archives after other filters were applied | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``--last N`` | consider last N archives after other filters were applied | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + + .. raw:: html + + + +.. only:: latex + + NAME + specify the archive name + + + optional arguments + -n, --dry-run do not change repository + --list output verbose list of archives + + + :ref:`common_options` + | + + Archive filters + -a PATTERN, --match-archives PATTERN only consider archives matching all patterns. see "borg help match-archives". + --sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp + --first N consider first N archives after other filters were applied + --last N consider last N archives after other filters were applied + --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. + --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. + --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d or 12m. + --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. + + +Description +~~~~~~~~~~~ + +This command undeletes archives in the repository. + +Important: Undeleting archives is only possible before compacting. +Once ``borg compact`` has run, all disk space occupied only by the +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. + +You can undelete multiple archives by specifying a matching pattern, +using the ``--match-archives PATTERN`` option (for more info on these patterns, +see :ref:`borg_patterns`). \ No newline at end of file