build_usage build_man

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

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

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

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

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

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)

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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.
-
-Differently than borg 1.x, borg2's compact needs the borg key if the repo is
-encrypted.
+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.
+
+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``).

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.
 

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

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.
+When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
+but other signals or crashes do not.

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

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

docs/usage/undelete.rst

@@ -0,0 +1 @@
+.. include:: undelete.rst.inc

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
+
+        <script type='text/javascript'>
+        $(document).ready(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
+
+.. 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`).