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-11-16" "" "borg backup tool"
+.TH "BORG-ANALYZE" "1" "2025-04-21" "" "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-11-16" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CPU" "1" "2025-04-21" "" "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-11-16" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CRUD" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .SH SYNOPSIS
@@ -47,11 +47,9 @@ If your repository is encrypted and borg needs a passphrase to unlock the key, u
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

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-11-16" "" "borg backup tool"
+.TH "BORG-BENCHMARK" "1" "2025-04-21" "" "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-11-16" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" "1" "2025-04-21" "" "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-11-16" "" "borg backup tool"
+.TH "BORG-CHECK" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .SH SYNOPSIS
@@ -44,7 +44,7 @@ the file magic headers, and both the metadata and data of all objects in
 the repository. The read data is checked by size and hash. Bit rot and other
 types of accidental damage can be detected this way. Running the repository
 check can be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
-When checking a \fI\%ssh://\fP remote repository, please note that the checks run on
+When checking a  <ssh://>  remote repository, please note that the checks run on
 the server and do not cause significant network traffic.
 .IP 2. 3
 Checking consistency and correctness of the archive metadata and optionally
@@ -137,37 +137,16 @@ objects from the repository after it did a 2nd try to read them correctly.
 .IP 2. 3
 When checking the consistency and correctness of archives, repair mode might
 remove whole archives from the manifest if their archive metadata chunk is
-corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
-will replace corrupt or lost chunks with a same\-size replacement chunk of
-zeroes. If a previously zeroed chunk reappears, repair mode will restore
-this lost chunk using the new chunk.
+corrupt or lost. Borg will also report files that reference missing chunks.
 .UNINDENT
 .sp
-Most steps taken by repair mode have a one\-time effect on the repository, like
-removing a lost archive from the repository. However, replacing a corrupt or
-lost chunk with an all\-zero replacement will have an ongoing effect on the
-repository: When attempting to extract a file referencing an all\-zero chunk,
-the \fBextract\fP command will distinctly warn about it. The FUSE filesystem
-created by the \fBmount\fP command will reject reading such a \(dqzero\-patched\(dq
-file unless a special mount option is given.
-.sp
-As mentioned earlier, Borg might be able to \(dqheal\(dq a \(dqzero\-patched\(dq file in
-repair mode, if all its previously lost chunks reappear (e.g. via a later
-backup). This is achieved by Borg not only keeping track of the all\-zero
-replacement chunks, but also by keeping metadata about the lost chunks. In
-repair mode Borg will check whether a previously lost chunk reappeared and will
-replace the all\-zero replacement chunk by the reappeared chunk. If all lost
-chunks of a \(dqzero\-patched\(dq file reappear, this effectively \(dqheals\(dq the file.
-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 \-\-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
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-repository\-only

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-11-16" "" "borg backup tool"
+.TH "BORG-COMMON" "1" "2025-04-21" "" "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-11-16" "" "borg backup tool"
+.TH "BORG-COMPACT" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-compact \- Collect garbage in repository
 .SH SYNOPSIS
@@ -70,19 +70,36 @@ archives directory corruption. Such archives could potentially be restored with
 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).
+.sp
+When giving the \fB\-\-stats\fP option, borg will internally list all repository
+objects to determine their existence AND stored size. It will build a fresh
+chunks index from that information and cache it in the repository. For some
+types of repositories, this might be very slow. It will tell you the sum of
+stored object sizes, before and after compaction.
+.sp
+Without \fB\-\-stats\fP, borg will rely on the cached chunks index to determine
+existing object IDs (but there is no stored size information in the index,
+thus it can\(aqt compute before/after compaction size statistics).
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS options
+.INDENT 0.0
+.TP
+.B  \-n\fP,\fB  \-\-dry\-run
+do nothing
+.TP
+.B  \-s\fP,\fB  \-\-stats
+print statistics (might be much slower)
+.UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # compact segments and free repo disk space
 $ borg compact
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-COMPRESSION" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .SH DESCRIPTION
@@ -103,16 +103,14 @@ Available factors:
 .INDENT 7.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 1:     0.01 ..        100
 2:     0.1  ..      1,000
 3:     1    ..     10,000
 4:    10    ..    100,000
 5:   100    ..  1,000,000
 6: 1,000    .. 10,000,000
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -120,14 +118,12 @@ Example probabilities for SPEC \fB1\fP:
 .INDENT 7.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 90   %  0.01 ..   0.1
  9   %  0.1  ..   1
  0.9 %  1    ..  10
  0.09% 10    .. 100
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -135,37 +131,47 @@ Example probabilities for SPEC \fB1\fP:
 .INDENT 7.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 110: 1kiB (2 ^ (SPEC \- 100))
 \&...
 120: 1MiB
 \&...
 123: 8MiB (max.)
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
+.sp
+\fIPadmé padding\fP (deterministic)
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.EX
+250: pads to sums of powers of 2, max 12% overhead
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+Uses the Padmé algorithm to deterministically pad the compressed size to a sum of
+powers of 2, limiting overhead to 12%. See  <https://lbarman.ch/blog/padme/>  for details.
 .UNINDENT
 .sp
 Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
-borg create \-\-compression lz4 REPO::ARCHIVE data
-borg create \-\-compression zstd REPO::ARCHIVE data
-borg create \-\-compression zstd,10 REPO::ARCHIVE data
-borg create \-\-compression zlib REPO::ARCHIVE data
-borg create \-\-compression zlib,1 REPO::ARCHIVE data
-borg create \-\-compression auto,lzma,6 REPO::ARCHIVE data
+.EX
+borg create \-\-compression lz4 \-\-repo REPO ARCHIVE data
+borg create \-\-compression zstd \-\-repo REPO ARCHIVE data
+borg create \-\-compression zstd,10 \-\-repo REPO ARCHIVE data
+borg create \-\-compression zlib \-\-repo REPO ARCHIVE data
+borg create \-\-compression zlib,1 \-\-repo REPO ARCHIVE data
+borg create \-\-compression auto,lzma,6 \-\-repo REPO ARCHIVE data
 borg create \-\-compression auto,lzma ...
 borg create \-\-compression obfuscate,110,none ...
 borg create \-\-compression obfuscate,3,auto,zstd,10 ...
 borg create \-\-compression obfuscate,2,zstd,6 ...
-.ft P
-.fi
+borg create \-\-compression obfuscate,250,zstd,3 ...
+.EE
 .UNINDENT
 .UNINDENT
 .SH AUTHOR

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-11-16" "" "borg backup tool"
+.TH "BORG-CREATE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .SH SYNOPSIS
@@ -137,7 +137,7 @@ specify the archive name
 .B PATH
 paths to archive
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run
@@ -195,7 +195,7 @@ include/exclude paths matching PATTERN
 read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .B  \-\-exclude\-caches
-exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
+exclude directories that contain a CACHEDIR.TAG file ( <http://www.bford.info/cachedir/spec.html> )
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
@@ -261,8 +261,7 @@ select compression algorithm, see the output of the \(dqborg help compression\(d
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Backup ~/Documents into an archive named \(dqmy\-documents\(dq
 $ borg create my\-documents ~/Documents
 
@@ -270,7 +269,7 @@ $ borg create my\-documents ~/Documents
 $ borg create \-\-list my\-documents ~/Documents
 
 # Backup /mnt/disk/docs, but strip path prefix using the slashdot hack
-$ borg create /path/to/repo::docs /mnt/disk/./docs
+$ borg create \-\-repo /path/to/repo docs /mnt/disk/./docs
 
 # Backup ~/Documents and ~/src but exclude pyc files
 $ borg create my\-files                \e
@@ -340,8 +339,7 @@ $ find ~ \-size \-1000k \-print0 | borg create \e
     \-\-paths\-from\-stdin \e
     \-\-paths\-delimiter \(dq\e0\(dq \e
     smallfiles\-handle\-newline
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH NOTES
@@ -432,11 +430,9 @@ pipe directly to borg:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
-backup\-vm \-\-id myvm \-\-stdout | borg create REPO::ARCHIVE \-
-.ft P
-.fi
+.EX
+backup\-vm \-\-id myvm \-\-stdout | borg create \-\-repo REPO ARCHIVE \-
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -447,11 +443,9 @@ to the command:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
-borg create \-\-content\-from\-command REPO::ARCHIVE \-\- backup\-vm \-\-id myvm \-\-stdout
-.ft P
-.fi
+.EX
+borg create \-\-content\-from\-command \-\-repo REPO ARCHIVE \-\- backup\-vm \-\-id myvm \-\-stdout
+.EE
 .UNINDENT
 .UNINDENT
 .sp

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-11-16" "" "borg backup tool"
+.TH "BORG-DELETE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete archives
 .SH SYNOPSIS
@@ -61,7 +61,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B NAME
 specify the archive name
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run
@@ -101,8 +101,7 @@ consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # delete all backup archives named \(dqkenny\-files\(dq:
 $ borg delete \-a kenny\-files
 # actually free disk space:
@@ -119,8 +118,7 @@ $ borg delete \-a \(aqsh:*\-2012\-*\(aq
 
 # see what would be deleted if delete was run without \-\-dry\-run
 $ borg delete \-\-list \-\-dry\-run \-a \(aqsh:*\-May\-*\(aq
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-DIFF" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .SH SYNOPSIS
@@ -53,7 +53,7 @@ ARCHIVE2 name
 .B PATH
 paths of items inside the archives to compare; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-numeric\-ids
@@ -93,8 +93,7 @@ read include/exclude patterns from PATTERNFILE, one per line
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg diff archive1 archive2
     +17 B      \-5 B [\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
    +135 B    \-252 B file2
@@ -106,21 +105,20 @@ $ borg diff archive1 archive2
 {\(dqpath\(dq: \(dqfile2\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: 135, \(dqremoved\(dq: 252}]}
 {\(dqpath\(dq: \(dqfile4\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqadded\(dq, \(dqsize\(dq: 0}]}
 {\(dqpath\(dq: \(dqfile3\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: 0}]}
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH NOTES
 .SS The FORMAT specifier syntax
 .sp
-The \fB\-\-format\fP option uses python\(aqs \fI\%format string syntax\fP\&.
+The \fB\-\-format\fP option uses python\(aqs format string syntax <https://docs.python.org/3.9/library/string.html#formatstrings>
+\&.
 .sp
 Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg diff \-\-format \(aq{content:30} {path}{NL}\(aq ArchiveFoo ArchiveBar
 modified:  +4.1 kB  \-1.0 kB    file\-diff
 \&...
@@ -130,8 +128,7 @@ modified:  +4.1 kB  \-1.0 kB    file\-diff
 $ borg diff \-\-format \(aq{content:>30} {path}{NL}\(aq ArchiveFoo ArchiveBar
    modified:  +4.1 kB  \-1.0 kB file\-diff
 \&...
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

docs/man/borg-export-tar.1

@@ -1,3 +1,4 @@
+'\" t
 .\" Man page generated from reStructuredText.
 .
 .
@@ -27,7 +28,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-11-16" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS
@@ -61,9 +62,8 @@ tar stream to stdout.
 .sp
 Depending on the \fB\-tar\-format\fP option, these formats are created:
 .TS
-center;
-|l|l|l|.
-_
+box center;
+l|l|l.
 T{
 \-\-tar\-format
 T}	T{
@@ -97,7 +97,6 @@ T}	T{
 mtime s, no atime/ctime,
 no ACLs/xattrs/bsdflags
 T}
-_
 .TE
 .sp
 A \fB\-\-sparse\fP option (as found in borg extract) is not supported.
@@ -125,7 +124,7 @@ output tar file. \(dq\-\(dq to write to stdout instead.
 .B PATH
 paths to extract; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-tar\-filter

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-11-16" "" "borg backup tool"
+.TH "BORG-EXTRACT" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .SH SYNOPSIS
@@ -72,7 +72,7 @@ specify the archive name
 .B PATH
 paths to extract; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-list
@@ -124,8 +124,7 @@ Remove the specified number of leading path elements. Paths with fewer elements
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Extract entire archive
 $ borg extract my\-files
 
@@ -143,8 +142,7 @@ $ borg extract my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq
 
 # Restore a raw device (must not be active/in use/mounted at that time)
 $ borg extract \-\-stdout my\-sdx | dd of=/dev/sdx bs=10M
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-IMPORT-TAR" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-import-tar \- Create a backup archive from a tarball
 .SH SYNOPSIS
@@ -96,7 +96,7 @@ specify the archive name
 .B TARFILE
 input tar file. \(dq\-\(dq to read from stdin instead.
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-tar\-filter
@@ -136,8 +136,7 @@ select compression algorithm, see the output of the \(dqborg help compression\(d
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # export as uncompressed tar
 $ borg export\-tar Monday Monday.tar
 
@@ -158,8 +157,7 @@ $ borg export\-tar Monday \- | curl \-\-data\-binary @\- https://somewhere/to/PO
 
 # remote extraction via \(dqtarpipe\(dq
 $ borg export\-tar Monday \- | ssh somewhere \(dqcd extracted; tar x\(dq
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SS Archives transfer script
@@ -168,14 +166,12 @@ Outputs a script that copies all archives from repo1 to repo2:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 for N I T in \(gaborg list \-\-format=\(aq{archive} {id} {time:%Y\-%m\-%dT%H:%M:%S}{NL}\(aq\(ga
 do
   echo \(dqborg \-r repo1 export\-tar \-\-tar\-format=BORG aid:$I \- | borg \-r repo2 import\-tar \-\-timestamp=$T $N \-\(dq
 done
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

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-11-16" "" "borg backup tool"
+.TH "BORG-INFO" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS
@@ -54,7 +54,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B NAME
 specify the archive name
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-json
@@ -91,8 +91,7 @@ consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg info aid:f7dea078
 Archive name: source\-backup
 Archive fingerprint: f7dea0788dfc026cc2be1c0f5b94beb4e4084eb3402fc40c38d8719b1bf2d943
@@ -107,8 +106,7 @@ Utilization of maximum supported archive size: 0%
 Number of files: 244
 Original size: 13.80 MB
 Deduplicated size: 531 B
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-LOCATION" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-key-change-location \- Change repository key location
 .SH SYNOPSIS
@@ -56,7 +56,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B KEY_LOCATION
 select key location
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-keep

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-11-16" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-PASSPHRASE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .SH SYNOPSIS
@@ -49,8 +49,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Create a key file protected repository
 $ borg repo\-create \-\-encryption=keyfile\-aes\-ocb \-v
 Initializing repository at \(dq/path/to/repo\(dq
@@ -75,8 +74,7 @@ Key updated
 # key file (creating or overwriting the output key)
 # (keyfile repositories only)
 $ BORG_KEY_FILE=/path/to/output\-key borg key import /path/to/exported
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -84,14 +82,12 @@ Fully automated using environment variables:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ BORG_NEW_PASSPHRASE=old borg repo\-create \-\-encryption=repokey\-aes\-ocb
 # now \(dqold\(dq is the current passphrase.
 $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase
 # now \(dqnew\(dq is the current passphrase.
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .SH SYNOPSIS
@@ -65,7 +65,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B PATH
 where to store the backup
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-paper
@@ -78,8 +78,7 @@ Create an html file suitable for printing and later type\-in or qr scan
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 borg key export > encrypted\-key\-backup
 borg key export \-\-paper > encrypted\-key\-backup.txt
 borg key export \-\-qr\-html > encrypted\-key\-backup.html
@@ -87,8 +86,7 @@ borg key export \-\-qr\-html > encrypted\-key\-backup.html
 borg key export encrypted\-key\-backup
 borg key export \-\-paper encrypted\-key\-backup.txt
 borg key export \-\-qr\-html encrypted\-key\-backup.html
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-KEY-IMPORT" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .SH SYNOPSIS
@@ -58,7 +58,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B PATH
 path to the backup (\(aq\-\(aq to read from stdin)
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-paper

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-11-16" "" "borg backup tool"
+.TH "BORG-KEY" "1" "2025-04-21" "" "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-11-16" "" "borg backup tool"
+.TH "BORG-LIST" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive contents
 .SH SYNOPSIS
@@ -50,7 +50,7 @@ specify the archive name
 .B PATH
 paths to list; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-short
@@ -81,8 +81,7 @@ read include/exclude patterns from PATTERNFILE, one per line
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg list root\-2016\-02\-15
 drwxr\-xr\-x root   root          0 Mon, 2016\-02\-15 17:44:27 .
 drwxrwxr\-x root   root          0 Mon, 2016\-02\-15 19:04:49 bin
@@ -114,21 +113,20 @@ $ borg list archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern \(aq\- re:^.*$\(
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
 \&...
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH NOTES
 .SS The FORMAT specifier syntax
 .sp
-The \fB\-\-format\fP option uses python\(aqs \fI\%format string syntax\fP\&.
+The \fB\-\-format\fP option uses python\(aqs format string syntax <https://docs.python.org/3.9/library/string.html#formatstrings>
+\&.
 .sp
 Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg list \-\-format \(aq{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(aq ArchiveFoo
 \-rw\-rw\-r\-\- user   user       1024 Thu, 2021\-12\-09 10:22:17 file\-foo
 \&...
@@ -138,8 +136,7 @@ $ borg list \-\-format \(aq{mode} {user:6} {group:6} {size:8} {mtime} {path}{ext
 $ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}\(aq ArchiveFoo
 \-rw\-rw\-r\-\-   user   user 1024     Thu, 2021\-12\-09 10:22:17 file\-foo
 \&...
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -231,8 +228,6 @@ archiveid: internal ID of the archive
 archivename: name of the archive
 .IP \(bu 2
 extra: prepends {target} with \(dq \-> \(dq for soft links and \(dq link to \(dq for hard links
-.IP \(bu 2
-health: either \(dqhealthy\(dq (file ok) or \(dqbroken\(dq (if file has all\-zero replacement chunks)
 .UNINDENT
 .SH SEE ALSO
 .sp

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-11-16" "" "borg backup tool"
+.TH "BORG-MATCH-ARCHIVES" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-match-archives \- Details regarding match-archives
 .SH DESCRIPTION
@@ -59,7 +59,8 @@ Simple string match, must fully match exactly as given.
 .B Shell\-style patterns, selector \fBsh:\fP
 Match like on the shell, wildcards like \fI*\fP and \fI?\fP work.
 .TP
-.B \fI\%Regular expressions\fP, selector \fBre:\fP
+.B Regular expressions <https://docs.python.org/3/library/re.html>
+, selector \fBre:\fP
 Full regular expression support.
 This is very powerful, but can also get rather complicated.
 .UNINDENT
@@ -68,8 +69,7 @@ Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # name match, id: style
 borg delete \-\-match\-archives \(aqid:archive\-with\-crap\(aq
 borg delete \-a \(aqid:archive\-with\-crap\(aq  # same, using short option
@@ -90,8 +90,7 @@ borg delete \-a \(aqhost:kenny\-pc\(aq
 
 # tags match
 borg delete \-a \(aqtags:TAG1\(aq \-a \(aqtags:TAG2\(aq
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH AUTHOR

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-11-16" "" "borg backup tool"
+.TH "BORG-MOUNT" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -91,9 +91,9 @@ Additional mount options supported by borg:
 \fBversions\fP: when used with a repository mount, this gives a merged, versioned
 view of the files in the archives. EXPERIMENTAL, layout may change in future.
 .IP \(bu 2
-\fBallow_damaged_files\fP: by default damaged files (where missing chunks were
-replaced with runs of zeros by \fBborg check \-\-repair\fP) are not readable and
-return EIO (I/O error). Set this option to read such files.
+\fBallow_damaged_files\fP: by default damaged files (where chunks are missing)
+will return EIO (I/O error) when trying to read the related parts of the file.
+Set this option to replace the missing parts with all\-zero bytes.
 .IP \(bu 2
 \fBignore_permissions\fP: for security reasons the \fBdefault_permissions\fP mount
 option is internally enforced by borg. \fBignore_permissions\fP can be given to
@@ -123,7 +123,7 @@ where to mount filesystem
 .B PATH
 paths to extract; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-f\fP,\fB  \-\-foreground

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-11-16" "" "borg backup tool"
+.TH "BORG-PATTERNS" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
@@ -65,7 +65,8 @@ style for a specific pattern, prefix it with two characters followed
 by a colon \(aq:\(aq (i.e. \fBfm:path/*\fP, \fBsh:path/**\fP).
 .INDENT 0.0
 .TP
-.B \fI\%Fnmatch\fP, selector \fBfm:\fP
+.B Fnmatch <https://docs.python.org/3/library/fnmatch.html>
+, selector \fBfm:\fP
 This is the default style for \fB\-\-exclude\fP and \fB\-\-exclude\-from\fP\&.
 These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching
 any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq
@@ -89,7 +90,8 @@ levels, \fB*\fP for matching zero or more arbitrary characters with the
 exception of any path separator, \fB{}\fP containing comma\-separated
 alternative patterns. A leading path separator is always removed.
 .TP
-.B \fI\%Regular expressions\fP, selector \fBre:\fP
+.B Regular expressions <https://docs.python.org/3/library/re.html>
+, selector \fBre:\fP
 Unlike shell patterns, regular expressions are not required to match the full
 path and any substring match is sufficient. It is strongly recommended to
 anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path
@@ -134,6 +136,15 @@ Exclusions can be passed via the command line option \fB\-\-exclude\fP\&. When u
 from within a shell, the patterns should be quoted to protect them from
 expansion.
 .sp
+Patterns matching special characters, e.g. white space, within a shell may
+require adjustments, such as putting quotation marks around the arguments.
+Example:
+Using bash, the following command line option would match and exclude \(dqitem name\(dq:
+\fB\-\-pattern=\(aq\-path/item name\(aq\fP
+Note that when patterns are used within a pattern file directly read by borg,
+e.g. when using \fB\-\-exclude\-from\fP or \fB\-\-patterns\-from\fP, there is no shell
+involved and thus no quotation marks are required.
+.sp
 The \fB\-\-exclude\-from\fP option permits loading exclusion patterns from a text
 file with one pattern per line. Lines empty or starting with the hash sign
 \(aq#\(aq after removing whitespace on both ends are ignored. The optional style
@@ -148,8 +159,7 @@ Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq:
 $ borg create \-e \(aq*.o\(aq archive /
 
@@ -179,8 +189,7 @@ sh:home/*/.thumbnails
 some file with spaces.txt
 EOF
 $ borg create \-\-exclude\-from exclude.txt archive /
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -225,8 +234,7 @@ Example:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Define the recursion root
 R /
 # Exclude all iso files in any directory
@@ -243,8 +251,7 @@ R /
 # Exclude all other files and directories
 # that are not specifically included earlier.
 \- **
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -252,11 +259,9 @@ R /
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg create \-\-dry\-run \-\-list \-\-patterns\-from patterns.txt archive
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -281,8 +286,7 @@ Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # back up pics, but not the ones from 2018, except the good ones:
 # note: using = is essential to avoid cmdline argument parsing issues.
 borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 archive pics
@@ -295,8 +299,7 @@ borg create \-\-exclude \(aqre:\e.iso(?i)$\(aq \-\-exclude \(aqsh:home/**/.*\(aq
 
 # use a file with patterns (recursion root \(aq/\(aq via command line):
 borg create \-\-patterns\-from patterns.lst archive /
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -304,8 +307,7 @@ The patterns.lst file could look like that:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # \(dqsh:\(dq pattern style is the default
 # exclude caches
 \- home/*/.cache
@@ -317,8 +319,7 @@ The patterns.lst file could look like that:
 \- home/*
 # don\(aqt even look in /dev, /proc, /run, /sys, /tmp (note: would exclude files like /device, too)
 ! re:^(dev|proc|run|sys|tmp)
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -326,13 +327,11 @@ You can specify recursion roots either on the command line or in a patternfile:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # these two commands do the same thing
 borg create \-\-exclude home/bobby/junk archive /home/bobby /home/susan
 borg create \-\-patterns\-from patternfile.lst archive
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -340,16 +339,14 @@ patternfile.lst:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # note that excludes use fm: by default and patternfiles use sh: by default.
 # therefore, we need to specify fm: to have the same exact behavior.
 P fm
 R /home/bobby
 R /home/susan
 \- home/bobby/junk
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

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-11-16" "" "borg backup tool"
+.TH "BORG-PLACEHOLDERS" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .SH DESCRIPTION
@@ -47,11 +47,13 @@ The full name of the machine in reverse domain name notation.
 .TP
 .B {now}
 The current local date and time, by default in ISO\-8601 format.
-You can also supply your own \fI\%format string\fP, e.g. {now:%Y\-%m\-%d_%H:%M:%S}
+You can also supply your own format string <https://docs.python.org/3.9/library/datetime.html#strftime-and-strptime-behavior>
+, e.g. {now:%Y\-%m\-%d_%H:%M:%S}
 .TP
 .B {utcnow}
 The current UTC date and time, by default in ISO\-8601 format.
-You can also supply your own \fI\%format string\fP, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
+You can also supply your own format string <https://docs.python.org/3.9/library/datetime.html#strftime-and-strptime-behavior>
+, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
 .TP
 .B {user}
 The user name (or UID, if no name is available) of the user running borg.
@@ -76,11 +78,9 @@ If literal curly braces need to be used, double them for escaping:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
-borg create /path/to/repo::{{literal_text}}
-.ft P
-.fi
+.EX
+borg create \-\-repo /path/to/repo {{literal_text}}
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -88,13 +88,11 @@ Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
-borg create /path/to/repo::{hostname}\-{user}\-{utcnow} ...
-borg create /path/to/repo::{hostname}\-{now:%Y\-%m\-%d_%H:%M:%S%z} ...
+.EX
+borg create \-\-repo /path/to/repo {hostname}\-{user}\-{utcnow} ...
+borg create \-\-repo /path/to/repo {hostname}\-{now:%Y\-%m\-%d_%H:%M:%S%z} ...
 borg prune \-a \(aqsh:{hostname}\-*\(aq ...
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

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-11-16" "" "borg backup tool"
+.TH "BORG-PRUNE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS
@@ -50,7 +50,8 @@ you run \fBborg compact\fP\&.
 .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
-\fI\%GFS\fP
+GFS <https://en.wikipedia.org/wiki/Backup_rotation_scheme#Grandfather-father-son>
+
 (Grandfather\-father\-son) backup rotation scheme.
 .sp
 The recommended way to use prune is to give the archive series name to it via the
@@ -67,10 +68,10 @@ from different machines) in one shared repository, use one prune call per
 series.
 .sp
 The \fB\-\-keep\-within\fP option takes an argument of the form \(dq<int><char>\(dq,
-where char is \(dqH\(dq, \(dqd\(dq, \(dqw\(dq, \(dqm\(dq, \(dqy\(dq. For example, \fB\-\-keep\-within 2d\fP means
-to keep all archives that were created within the past 48 hours.
-\(dq1m\(dq is taken to mean \(dq31d\(dq. The archives kept with this option do not
-count towards the totals specified by any other options.
+where char is \(dqy\(dq, \(dqm\(dq, \(dqw\(dq, \(dqd\(dq, \(dqH\(dq, \(dqM\(dq, or \(dqS\(dq.  For example,
+\fB\-\-keep\-within 2d\fP means to keep all archives that were created within
+the past 2 days.  \(dq1m\(dq is taken to mean \(dq31d\(dq. The archives kept with
+this option do not count towards the totals specified by any other options.
 .sp
 A good procedure is to thin out more and more the older your backups get.
 As an example, \fB\-\-keep\-daily 7\fP means to keep the latest backup on each day,
@@ -106,7 +107,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B NAME
 specify the archive name
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run
@@ -199,8 +200,7 @@ Don\(aqt forget to run \fBborg compact \-v\fP after prune to actually free disk
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Keep 7 end of day and 4 additional end of week archives.
 # Do a dry\-run without actually deleting anything.
 $ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4
@@ -219,8 +219,7 @@ $ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-keep\-monthly
 # Keep all backups in the last 10 days, 4 additional end of week archives,
 # and an end of month archive for every month:
 $ borg prune \-v \-\-list \-\-keep\-within=10d \-\-keep\-weekly=4 \-\-keep\-monthly=\-1
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

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-11-16" "" "borg backup tool"
+.TH "BORG-RECREATE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .SH SYNOPSIS
@@ -69,16 +69,10 @@ When rechunking, space usage can be substantial \- expect
 at least the entire deduplicated size of the archives using the previous
 chunker params.
 .sp
-If you recently ran borg check \-\-repair and it had to fix lost chunks with all\-zero
-replacement chunks, please first run another backup for the same data and re\-run
-borg check \-\-repair afterwards to heal any archives that had lost chunks which are
-still generated from the input data.
-.sp
-Important: running borg recreate to re\-chunk will remove the chunks_healthy
-metadata of all items with replacement chunks, so healing will not be possible
-any more after re\-chunking (it is also unlikely it would ever work: due to the
-change of chunking parameters, the missing chunk likely will never be seen again
-even if you still have the data that produced it).
+If your most recent borg check found missing chunks, please first run another
+backup for the same data, before doing any rechunking. If you are lucky, that
+will re\-create the missing chunks. Optionally, do another borg check, to see
+if the chunks are still missing).
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -88,7 +82,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B PATH
 paths to recreate; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-list
@@ -119,7 +113,7 @@ include/exclude paths matching PATTERN
 read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .B  \-\-exclude\-caches
-exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
+exclude directories that contain a CACHEDIR.TAG file ( <http://www.bford.info/cachedir/spec.html> )
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
@@ -173,8 +167,7 @@ rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Create a backup with little but fast compression
 $ borg create archive /some/files \-\-compression lz4
 # Then compress it \- this might take longer, but the backup has already completed,
@@ -198,8 +191,7 @@ Name: archivename
 Fingerprint: ...
 Comment: This is a better comment
 \&...
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-RENAME" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .SH SYNOPSIS
@@ -54,8 +54,7 @@ specify the new archive name
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg create archivename ~
 $ borg repo\-list
 archivename                          Mon, 2016\-02\-15 19:50:19
@@ -63,8 +62,7 @@ archivename                          Mon, 2016\-02\-15 19:50:19
 $ borg rename archivename newname
 $ borg repo\-list
 newname                              Mon, 2016\-02\-15 19:50:19
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-REPO-COMPRESS" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-repo-compress \- Repository (re-)compression
 .SH SYNOPSIS
@@ -58,7 +58,7 @@ You do \fBnot\fP need to run \fBborg compact\fP after \fBborg repo\-compress\fP\
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
@@ -71,15 +71,13 @@ print statistics
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # recompress repo contents
 $ borg repo\-compress \-\-progress \-\-compression=zstd,3
 
 # recompress and obfuscate repo contents
 $ borg repo\-compress \-\-progress \-\-compression=obfuscate,1,zstd,3
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

docs/man/borg-repo-create.1

@@ -1,3 +1,4 @@
+'\" t
 .\" Man page generated from reStructuredText.
 .
 .
@@ -27,7 +28,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-11-16" "" "borg backup tool"
+.TH "BORG-REPO-CREATE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-repo-create \- Create a new, empty repository
 .SH SYNOPSIS
@@ -50,11 +51,9 @@ tips will come below):
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 borg repo\-create \-\-encryption repokey\-aes\-ocb
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -122,9 +121,8 @@ in the upper part of the table, in the lower part is the old and/or unsafe(r) st
 .\" nanorst: inline-fill
 .
 .TS
-center;
-|l|l|l|l|.
-_
+box center;
+l|l|l|l.
 T{
 Mode (K = keyfile or repokey)
 T}	T{
@@ -204,7 +202,6 @@ none
 T}	T{
 none
 T}
-_
 .TE
 .\" nanorst: inline-replace
 .
@@ -239,7 +236,7 @@ Then use \fBborg transfer \-\-other\-repo ORIG_REPO \-\-from\-borg1 ...\fP to tr
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .BI \-\-other\-repo \ SRC_REPOSITORY
@@ -257,9 +254,6 @@ create an append\-only mode repository. Note that this only affects the low leve
 .BI \-\-storage\-quota \ QUOTA
 Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
 .TP
-.B  \-\-make\-parent\-dirs
-create the parent directories of the repository directory, if they are missing.
-.TP
 .B  \-\-copy\-crypt\-key
 copy the crypt_key (used for authenticated encryption) from the key of the other repo (default: new random key).
 .UNINDENT
@@ -267,8 +261,7 @@ copy the crypt_key (used for authenticated encryption) from the key of the other
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Local repository
 $ export BORG_REPO=/path/to/repo
 # recommended repokey AEAD crypto modes
@@ -287,8 +280,7 @@ $ export BORG_REPO=ssh://user@hostname/~/backup
 $ borg repo\-create \-\-encryption=repokey\-aes\-ocb
 # keyfile: stores the (encrypted) key into ~/.config/borg/keys/
 $ borg repo\-create \-\-encryption=keyfile\-aes\-ocb
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-REPO-DELETE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-repo-delete \- Delete a repository
 .SH SYNOPSIS
@@ -46,7 +46,7 @@ Always first use \fB\-\-dry\-run \-\-list\fP to see what would be deleted.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run
@@ -68,8 +68,7 @@ keep the local security info when deleting a repository
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # delete the whole repository and the related local cache:
 $ borg repo\-delete
 You requested to DELETE the repository completely *including* all archives it contains:
@@ -77,8 +76,7 @@ repo                                 Mon, 2016\-02\-15 19:26:54
 root\-2016\-02\-15                      Mon, 2016\-02\-15 19:36:29
 newname                              Mon, 2016\-02\-15 19:50:19
 Type \(aqYES\(aq if you understand this and want to continue: YES
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-REPO-INFO" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-repo-info \- Show repository infos
 .SH SYNOPSIS
@@ -39,7 +39,7 @@ This command displays detailed information about the repository.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-json
@@ -49,8 +49,7 @@ format output as JSON
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg repo\-info
 Repository ID: 0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9
 Location: /Users/tw/w/borg/path/to/repo
@@ -61,8 +60,7 @@ Original size: 152.14 MB
 Deduplicated size: 30.38 MB
 Unique chunks: 654
 Total chunks: 3302
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-REPO-LIST" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-repo-list \- List the archives contained in a repository
 .SH SYNOPSIS
@@ -39,7 +39,7 @@ This command lists the archives contained in a repository.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-short
@@ -85,8 +85,7 @@ consider only soft\-deleted archives.
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg repo\-list
 151b1a57  Mon, 2024\-09\-23 22:57:11 +0200  docs             tw          MacBook\-Pro  this is a comment
 3387a079  Thu, 2024\-09\-26 09:07:07 +0200  scripts          tw          MacBook\-Pro
@@ -95,21 +94,20 @@ ba56c4a5  Thu, 2024\-09\-26 10:12:45 +0200  src              tw          MacBook
 7567b79a  Thu, 2024\-09\-26 10:15:07 +0200  scripts          tw          MacBook\-Pro
 21ab3600  Thu, 2024\-09\-26 10:15:17 +0200  docs             tw          MacBook\-Pro
 \&...
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH NOTES
 .SS The FORMAT specifier syntax
 .sp
-The \fB\-\-format\fP option uses python\(aqs \fI\%format string syntax\fP\&.
+The \fB\-\-format\fP option uses python\(aqs format string syntax <https://docs.python.org/3.9/library/string.html#formatstrings>
+\&.
 .sp
 Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg repo\-list \-\-format \(aq{archive}{NL}\(aq
 ArchiveFoo
 ArchiveBar
@@ -121,8 +119,7 @@ ArchiveBar
 $ borg repo\-list \-\-format \(aq{archive:36} {time} [{id}]{NL}\(aq /path/to/repo
 ArchiveFoo                           Thu, 2021\-12\-09 10:22:28 [0b8e9...3b274]
 \&...
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

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-11-16" "" "borg backup tool"
+.TH "BORG-REPO-SPACE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-repo-space \- Manage reserved space in repository
 .SH SYNOPSIS
@@ -51,8 +51,7 @@ Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Create a new repository:
 $ borg repo\-create ...
 # Reserve approx. 1GB of space for emergencies:
@@ -67,8 +66,7 @@ $ borg prune ...
 $ borg delete ...
 $ borg compact \-v  # only this actually frees space of deleted archives
 $ borg repo\-space \-\-reserve 1G  # reserve space again for next time
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -76,7 +74,7 @@ Reserved space is always rounded up to use full reservation blocks of 64MiB.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .BI \-\-reserve \ SPACE

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-11-16" "" "borg backup tool"
+.TH "BORG-SERVE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .SH SYNOPSIS
@@ -40,7 +40,7 @@ This command starts a repository server process.
 borg serve can currently support:
 .INDENT 0.0
 .IP \(bu 2
-Getting automatically started via ssh when the borg client uses a \fI\%ssh://\fP\&...
+Getting automatically started via ssh when the borg client uses a  <ssh://> \&...
 remote repository. In this mode, \fIborg serve\fP will live until that ssh connection
 gets terminated.
 .IP \(bu 2
@@ -51,7 +51,7 @@ option if you do not want to use the default path for the socket and pid file).
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .BI \-\-restrict\-to\-path \ PATH
@@ -89,8 +89,7 @@ locations like \fB/etc/environment\fP or in the forced command itself (example b
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Allow an SSH keypair to run only borg, and only have access to /path/to/repo.
 # Use key options to disable unneeded and potentially dangerous SSH functionality.
 # This will help to secure an automated remote backup system.
@@ -100,8 +99,7 @@ command=\(dqborg serve \-\-restrict\-to\-path /path/to/repo\(dq,restrict ssh\-rs
 # Set a BORG_XXX environment variable on the \(dqborg serve\(dq side
 $ cat ~/.ssh/authorized_keys
 command=\(dqexport BORG_XXX=value; borg serve [...]\(dq,restrict ssh\-rsa [...]
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -120,7 +118,8 @@ in this case.
 .UNINDENT
 .UNINDENT
 .sp
-Details about sshd usage: \fI\%sshd(8)\fP
+Details about sshd usage: sshd(8) <https://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man8/sshd.8>
+
 .SS SSH Configuration
 .sp
 \fBborg serve\fP\(aqs pipes (\fBstdin\fP/\fBstdout\fP/\fBstderr\fP) are connected to the \fBsshd\fP process on the server side. In the event that the SSH connection between \fBborg serve\fP and the client is disconnected or stuck abnormally (for example, due to a network outage), it can take a long time for \fBsshd\fP to notice the client is disconnected. In the meantime, \fBsshd\fP continues running, and as a result so does the \fBborg serve\fP process holding the lock on the repository. This can cause subsequent \fBborg\fP operations on the remote repository to fail with the error: \fBFailed to create/acquire the lock\fP\&.
@@ -131,13 +130,11 @@ Either in the client side\(aqs \fB~/.ssh/config\fP file, or in the client\(aqs \
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 Host backupserver
         ServerAliveInterval 10
         ServerAliveCountMax 30
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -149,12 +146,10 @@ On the server side\(aqs \fBsshd\fP configuration file (typically \fB/etc/ssh/ssh
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 ClientAliveInterval 10
 ClientAliveCountMax 30
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -163,6 +158,26 @@ This will cause the server to send a keep alive to the client every 10 seconds.
 If you then run borg commands with \fB\-\-lock\-wait 600\fP, this gives sufficient time for the borg serve processes to terminate after the SSH connection is torn down after the 300 second wait for the keepalives to fail.
 .sp
 You may, of course, modify the timeout values demonstrated above to values that suit your environment and use case.
+.sp
+When the client is untrusted, it is a good idea to set the backup
+user\(aqs shell to a simple implementation (\fB/bin/sh\fP is only an example and may or may
+not be such a simple implementation):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+chsh \-s /bin/sh BORGUSER
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+Because the configured shell is used by openssh <https://www.openssh.com/>
+
+to execute the command configured through the \fBauthorized_keys\fP file
+using \fB\(dq$SHELL\(dq \-c \(dq$COMMAND\(dq\fP,
+setting a minimal shell implementation reduces the attack surface
+compared to when a feature\-rich and complex shell implementation is
+used.
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP

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-11-16" "" "borg backup tool"
+.TH "BORG-TAG" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-tag \- Manage tags
 .SH SYNOPSIS
@@ -59,7 +59,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B NAME
 specify the archive name
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .BI \-\-set \ TAG

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-11-16" "" "borg backup tool"
+.TH "BORG-TRANSFER" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-transfer \- archives transfer from other repository, optionally upgrade data format
 .SH SYNOPSIS
@@ -57,8 +57,7 @@ Transfer borg2 archives into a related other borg2 repository:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # create a related DST_REPO (reusing key material from SRC_REPO), so that
 # chunking and chunk id generation will work in the same way as before.
 borg \-\-repo=DST_REPO repo\-create \-\-encryption=DST_ENC \-\-other\-repo=SRC_REPO
@@ -67,8 +66,7 @@ borg \-\-repo=DST_REPO repo\-create \-\-encryption=DST_ENC \-\-other\-repo=SRC_R
 borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-dry\-run  # check what it would do
 borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO            # do it!
 borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-dry\-run  # check! anything left?
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SS Data migration / upgrade from borg 1.x
@@ -78,8 +76,7 @@ to the above, but you need the \fB\-\-from\-borg1\fP option:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 borg \-\-repo=DST_REPO repocreate \-\-encryption=DST_ENC \-\-other\-repo=SRC_REPO \-\-from\-borg1
 
 # to continue using lz4 compression as you did in SRC_REPO:
@@ -89,14 +86,13 @@ borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-from\-borg1 \e
 # alternatively, to recompress everything to zstd,3:
 borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-from\-borg1 \e
      \-\-compress=zstd,3 \-\-recompress=always
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run
@@ -148,8 +144,7 @@ consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # 0. Have borg 2.0 installed on client AND server, have a b12 repo copy for testing.
 
 # 1. Create a new \(dqrelated\(dq repository:
@@ -175,8 +170,7 @@ $ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=F
 # 4. Check if we have everything (same as 2.):
 $ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e
        \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

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-11-16" "" "borg backup tool"
+.TH "BORG-UMOUNT" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .SH SYNOPSIS
@@ -52,8 +52,7 @@ mountpoint of the filesystem to umount
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Mounting the repository shows all archives.
 # Archives are loaded lazily, expect some delay when navigating to an archive
 # for the first time.
@@ -80,22 +79,19 @@ $ borg mount \-o versions \-\-match\-archives \(aqsh:*\-my\-home\(aq \-\-last 10
 # These can speed up mounting and lower memory needs significantly.
 $ borg mount /path/to/repo /tmp/mymountpoint only/that/path
 $ borg mount \-\-exclude \(aq...\(aq /tmp/mymountpoint
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SS borgfs
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ echo \(aq/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
 $ mount /tmp/myrepo
 $ ls /tmp/myrepo
 root\-2016\-02\-01 root\-2016\-02\-2015
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

docs/man/borg-undelete.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-UNDELETE" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-UNDELETE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-undelete \- Undelete archives
 .SH SYNOPSIS
@@ -56,7 +56,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .B NAME
 specify the archive name
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run

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-11-16" "" "borg backup tool"
+.TH "BORG-VERSION" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-version \- Display the borg client / borg server version
 .SH SYNOPSIS
@@ -47,8 +47,7 @@ Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # local repo (client uses 1.4.0 alpha version)
 $ borg version /mnt/backup
 1.4.0a / 1.4.0a
@@ -56,8 +55,7 @@ $ borg version /mnt/backup
 # remote repo (client uses 1.4.0 alpha, server uses 1.2.7 release)
 $ borg version ssh://borg@borgbackup:repo
 1.4.0a / 1.2.7
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

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-11-16" "" "borg backup tool"
+.TH "BORG-WITH-LOCK" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .SH SYNOPSIS
@@ -39,11 +39,9 @@ This command runs a user\-specified command while locking the repository. For ex
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ BORG_REPO=/mnt/borgrepo borg with\-lock rsync \-av /mnt/borgrepo /somewhere/else/borgrepo
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

docs/man/borg.1

@@ -1,3 +1,4 @@
+'\" t
 .\" Man page generated from reStructuredText.
 .
 .
@@ -27,7 +28,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-11-16" "" "borg backup tool"
+.TH "BORG" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS
@@ -58,11 +59,9 @@ Before a backup can be made, a repository has to be initialized:
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg \-r /path/to/repo repo\-create \-\-encryption=repokey\-aes\-ocb
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .IP 2. 3
@@ -71,11 +70,9 @@ Back up the \fB~/src\fP and \fB~/Documents\fP directories into an archive called
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg \-r /path/to/repo create docs ~/src ~/Documents
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .IP 3. 3
@@ -83,11 +80,9 @@ The next day create a new archive using the same archive name:
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg \-r /path/to/repo create \-\-stats docs ~/src ~/Documents
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -98,8 +93,7 @@ size (the amount of unique data not shared with other archives):
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 Repository: /path/to/repo
 Archive name: docs
 Archive fingerprint: bcd1b53f9b4991b7afc2b339f851b7ffe3c6d030688936fe4552eccc1877718d
@@ -110,8 +104,7 @@ Utilization of max. archive size: 0%
 Number of files: 699
 Original size: 31.14 MB
 Deduplicated size: 502 B
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .IP 4. 3
@@ -119,13 +112,11 @@ List all archives in the repository:
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg \-r /path/to/repo repo\-list
 docs                                 Sat, 2022\-06\-25 20:21:14 [b80e24d2...b179f298]
 docs                                 Sat, 2022\-06\-25 20:21:43 [bcd1b53f...1877718d]
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .IP 5. 3
@@ -133,14 +124,12 @@ List the contents of the first archive:
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg \-r /path/to/repo list aid:b80e24d2
 drwxr\-xr\-x user   group          0 Mon, 2016\-02\-15 18:22:30 home/user/Documents
 \-rw\-r\-\-r\-\- user   group       7961 Mon, 2016\-02\-15 18:22:30 home/user/Documents/Important.doc
 \&...
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .IP 6. 3
@@ -148,11 +137,9 @@ Restore the first archive by extracting the files relative to the current direct
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg \-r /path/to/repo extract aid:b80e24d2
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .IP 7. 3
@@ -160,11 +147,9 @@ Delete the first archive (please note that this does \fBnot\fP free repo disk sp
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg \-r /path/to/repo delete aid:b80e24d2
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -175,11 +160,9 @@ Recover disk space by compacting the segment files in the repo:
 .INDENT 3.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 $ borg \-r /path/to/repo compact \-v
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .UNINDENT
@@ -203,18 +186,16 @@ in the example), but not in between them:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 borg create \-s \-\-progress archive path  # good and preferred
 borg create archive path \-s \-\-progress  # also works
 borg create \-s archive path \-\-progress  # works, but ugly
 borg create archive \-s \-\-progress path  # BAD
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
-This is due to a problem in the argparse module: \fI\%https://bugs.python.org/issue15112\fP
+This is due to a problem in the argparse module:  <https://bugs.python.org/issue15112> 
 .SS Repository URLs
 .sp
 \fBLocal filesystem\fP (or locally mounted network filesystem):
@@ -228,7 +209,7 @@ expanded by your shell).
 .sp
 Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style.
 .sp
-\fBRemote repositories\fP accessed via ssh \fI\%user@host\fP:
+\fBRemote repositories\fP accessed via ssh  <user@host> :
 .sp
 \fBssh://user@host:port//abs/path/to/repo\fP \- absolute path
 .sp
@@ -251,11 +232,9 @@ If you frequently need the same repo URL, it is a good idea to set the
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 export BORG_REPO=\(aqssh://user@host:port/rel/path/to/repo\(aq
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -285,11 +264,9 @@ If you want to capture the log output to a file, just redirect it:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
-borg create repo::archive myfiles 2>> logfile
-.ft P
-.fi
+.EX
+borg create \-\-repo repo archive myfiles 2>> logfile
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -331,9 +308,8 @@ their usage is not recommended as you might miss important information.
 .sp
 Borg can exit with the following return codes (rc):
 .TS
-center;
-|l|l|.
-_
+box center;
+l|l.
 T{
 Return code
 T}	T{
@@ -377,7 +353,6 @@ T{
 T}	T{
 killed by signal N (e.g. 137 == kill \-9)
 T}
-_
 .TE
 .sp
 If you use \fB\-\-show\-rc\fP, the return code is also logged at the indicated
@@ -442,14 +417,15 @@ a unique id based on the MAC address of the network interface. Except if that MA
 that case it returns a random value, which is not what we want (because it kills automatic stale lock removal).
 So, if you have a all\-zero MAC address or other reasons to control better externally the host id, just set this
 environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not,
-use \fI\%fqdn@uniqueid\fP\&.
+use  <fqdn@uniqueid> \&.
 .TP
 .B BORG_LOCK_WAIT
 You can set the default value for the \fB\-\-lock\-wait\fP option with this, so
 you do not need to give it as a commandline option.
 .TP
 .B BORG_LOGGING_CONF
-When set, use the given filename as \fI\%INI\fP\-style logging configuration.
+When set, use the given filename as INI <https://docs.python.org/3/library/logging.config.html#configuration-file-format>
+\-style logging configuration.
 A basic example conf can be found at \fBdocs/misc/logging.conf\fP\&.
 .TP
 .B BORG_RSH
@@ -534,11 +510,9 @@ from an affected repository (read\-only access):
 .INDENT 7.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
-BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive
-.ft P
-.fi
+.EX
+BORG_WORKAROUNDS=authenticated_no_key borg extract \-\-repo repo archive
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -546,11 +520,9 @@ After you have extracted all data you need, you MUST delete the repository:
 .INDENT 7.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 BORG_WORKAROUNDS=authenticated_no_key borg delete repo
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -604,26 +576,30 @@ to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt
 .TP
 .B BORG_CACHE_DIR
 Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
-\fI\%XDG env var\fP \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead.
+XDG env var <https://specifications.freedesktop.org/basedir-spec/0.6/ar01s03.html>
+ \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead.
 This directory contains the local cache and might need a lot
 of space for dealing with big repositories. Make sure you\(aqre aware of the associated
 security aspects of the cache location: \fIcache_security\fP
 .TP
 .B BORG_CONFIG_DIR
 Defaults to \fB$BORG_BASE_DIR/.config/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
-\fI\%XDG env var\fP \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead.
+XDG env var <https://specifications.freedesktop.org/basedir-spec/0.6/ar01s03.html>
+ \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead.
 This directory contains all borg configuration directories, see the FAQ
 for a security advisory about the data in this directory: \fIhome_config_borg\fP
 .TP
 .B BORG_DATA_DIR
 Defaults to \fB$BORG_BASE_DIR/.local/share/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
-\fI\%XDG env var\fP \fBXDG_DATA_HOME\fP is set, then \fB$XDG_DATA_HOME/borg\fP is being used instead.
+XDG env var <https://specifications.freedesktop.org/basedir-spec/0.6/ar01s03.html>
+ \fBXDG_DATA_HOME\fP is set, then \fB$XDG_DATA_HOME/borg\fP is being used instead.
 This directory contains all borg data directories, see the FAQ
 for a security advisory about the data in this directory: \fIhome_data_borg\fP
 .TP
 .B BORG_RUNTIME_DIR
 Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
-\fI\%XDG env var\fP \fBXDG_RUNTIME_DIR\fP is set, then \fB$XDG_RUNTIME_DIR/borg\fP is being used instead.
+XDG env var <https://specifications.freedesktop.org/basedir-spec/0.6/ar01s03.html>
+ \fBXDG_RUNTIME_DIR\fP is set, then \fB$XDG_RUNTIME_DIR/borg\fP is being used instead.
 This directory contains borg runtime files, like e.g. the socket file.
 .TP
 .B BORG_SECURITY_DIR
@@ -656,7 +632,8 @@ you need to point to the correct key file matching the repository the command wi
 .TP
 .B TMPDIR
 This is where temporary files are stored (might need a lot of temporary space for some
-operations), see \fI\%tempfile\fP for details.
+operations), see tempfile <https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir>
+ for details.
 .UNINDENT
 .TP
 .B Building:
@@ -738,23 +715,28 @@ Sometimes slower, due to less sequential / more random access operations.
 .SS Units
 .sp
 To display quantities, Borg takes care of respecting the
-usual conventions of scale. Disk sizes are displayed in \fI\%decimal\fP, using powers of ten (so
-\fBkB\fP means 1000 bytes). For memory usage, \fI\%binary prefixes\fP are used, and are
-indicated using the \fI\%IEC binary prefixes\fP,
+usual conventions of scale. Disk sizes are displayed in decimal <https://en.wikipedia.org/wiki/Decimal>
+, using powers of ten (so
+\fBkB\fP means 1000 bytes). For memory usage, binary prefixes <https://en.wikipedia.org/wiki/Binary_prefix>
+ are used, and are
+indicated using the IEC binary prefixes <https://en.wikipedia.org/wiki/IEC_80000-13#Prefixes_for_binary_multiples>
+,
 using powers of two (so \fBKiB\fP means 1024 bytes).
 .SS Date and Time
 .sp
 We format date and time conforming to ISO\-8601, that is: YYYY\-MM\-DD and
 HH:MM:SS (24h clock).
 .sp
-For more information about that, see: \fI\%https://xkcd.com/1179/\fP
+For more information about that, see:  <https://xkcd.com/1179/> 
 .sp
 Unless otherwise noted, we display local date and time.
 Internally, we store and process date and time as UTC.
 TIMESPAN
 .sp
-Some options accept a TIMESPAN parameter, which can be given as a
-number of days (e.g. \fB7d\fP) or months (e.g. \fB12m\fP).
+Some options accept a TIMESPAN parameter, which can be given as a number of
+years (e.g. \fB2y\fP), months (e.g. \fB12m\fP), weeks (e.g. \fB2w\fP),
+days (e.g.  \fB7d\fP), hours (e.g. \fB8H\fP), minutes (e.g. \fB30M\fP),
+or seconds (e.g. \fB150S\fP).
 .SS Resource Usage
 .sp
 Borg might use a lot of resources depending on the size of the data set it is dealing with.
@@ -798,7 +780,7 @@ borg check: the repository check computes the checksums of all chunks
 borg delete repo: low CPU usage
 .TP
 .B CPU (only for client/server operation):
-When using borg in a client/server way with a \fI\%ssh:\-type\fP repo, the ssh
+When using borg in a client/server way with a  <ssh:\-type>  repo, the ssh
 processes used for the transport layer will need some CPU on the client and
 on the server due to the crypto they are doing \- esp. if you are pumping
 big amounts of data.
@@ -898,9 +880,8 @@ On some platforms additional features are supported:
 .\" Yes/No's are grouped by reason/mechanism/reference.
 .
 .TS
-center;
-|l|l|l|l|.
-_
+box center;
+l|l|l|l.
 T{
 Platform
 T}	T{
@@ -983,7 +964,6 @@ No
 T}	T{
 No
 T}
-_
 .TE
 .sp
 Other Unix\-like operating systems may work as well, but have not been tested at all.
@@ -1021,15 +1001,15 @@ The BSDs define additional flags.
 \fIborg\-compression(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP
 .INDENT 0.0
 .IP \(bu 2
-Main web site \fI\%https://www.borgbackup.org/\fP
+Main web site  <https://www.borgbackup.org/> 
 .IP \(bu 2
-Releases \fI\%https://github.com/borgbackup/borg/releases\fP
+Releases  <https://github.com/borgbackup/borg/releases> 
 .IP \(bu 2
-Changelog \fI\%https://github.com/borgbackup/borg/blob/master/docs/changes.rst\fP
+Changelog  <https://github.com/borgbackup/borg/blob/master/docs/changes.rst> 
 .IP \(bu 2
-GitHub \fI\%https://github.com/borgbackup/borg\fP
+GitHub  <https://github.com/borgbackup/borg> 
 .IP \(bu 2
-Security contact \fI\%https://borgbackup.readthedocs.io/en/latest/support.html#security\-contact\fP
+Security contact  <https://borgbackup.readthedocs.io/en/latest/support.html#security\-contact> 
 .UNINDENT
 .SH AUTHOR
 The Borg Collective

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-11-16" "" "borg backup tool"
+.TH "BORGFS" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -48,7 +48,7 @@ where to mount filesystem
 .B PATH
 paths to extract; patterns are supported
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-V\fP,\fB  \-\-version

docs/usage/check.rst.inc

@@ -13,7 +13,7 @@ borg check
     .. class:: borg-options-table
 
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                   |
+    | **options**                                                                                                                                                                                                                                              |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--repository-only``                        | only perform repository checks                                                                                              |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -62,7 +62,7 @@ borg check
 
 
 
-    optional arguments
+    options
         --repository-only    only perform repository checks
         --archives-only    only perform archives checks
         --verify-data     perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
@@ -186,28 +186,7 @@ In practice, repair mode hooks into both the repository and archive checks:
 
 2. When checking the consistency and correctness of archives, repair mode might
    remove whole archives from the manifest if their archive metadata chunk is
-   corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
-   will replace corrupt or lost chunks with a same-size replacement chunk of
-   zeroes. If a previously zeroed chunk reappears, repair mode will restore
-   this lost chunk using the new chunk.
-
-Most steps taken by repair mode have a one-time effect on the repository, like
-removing a lost archive from the repository. However, replacing a corrupt or
-lost chunk with an all-zero replacement will have an ongoing effect on the
-repository: When attempting to extract a file referencing an all-zero chunk,
-the ``extract`` command will distinctly warn about it. The FUSE filesystem
-created by the ``mount`` command will reject reading such a "zero-patched"
-file unless a special mount option is given.
-
-As mentioned earlier, Borg might be able to "heal" a "zero-patched" file in
-repair mode, if all its previously lost chunks reappear (e.g. via a later
-backup). This is achieved by Borg not only keeping track of the all-zero
-replacement chunks, but also by keeping metadata about the lost chunks. In
-repair mode Borg will check whether a previously lost chunk reappeared and will
-replace the all-zero replacement chunk by the reappeared chunk. If all lost
-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.
+   corrupt or lost. Borg will also report files that reference missing chunks.
 
 If ``--repair --find-lost-archives`` is given, previously lost entries will
 be recreated in the archive directory. This is only possible before

docs/usage/compact.rst.inc

@@ -12,11 +12,17 @@ borg compact
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                        |
-    |                                                       |
-    | :ref:`common_options`                                 |
-    +-------------------------------------------------------+
+    +-------------------------------------------------------+-----------------------+-----------------------------------------+
+    | **options**                                                                                                             |
+    +-------------------------------------------------------+-----------------------+-----------------------------------------+
+    |                                                       | ``-n``, ``--dry-run`` | do nothing                              |
+    +-------------------------------------------------------+-----------------------+-----------------------------------------+
+    |                                                       | ``-s``, ``--stats``   | print statistics (might be much slower) |
+    +-------------------------------------------------------+-----------------------+-----------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                          |
+    |                                                                                                                         |
+    | :ref:`common_options`                                                                                                   |
+    +-------------------------------------------------------+-----------------------+-----------------------------------------+
 
     .. raw:: html
 
@@ -30,6 +36,11 @@ borg compact
 
 
 
+    options
+        -n, --dry-run    do nothing
+        -s, --stats     print statistics (might be much slower)
+
+
     :ref:`common_options`
         |
 
@@ -65,4 +76,14 @@ 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``).
+``borg repo-list``).
+
+When giving the ``--stats`` option, borg will internally list all repository
+objects to determine their existence AND stored size. It will build a fresh
+chunks index from that information and cache it in the repository. For some
+types of repositories, this might be very slow. It will tell you the sum of
+stored object sizes, before and after compaction.
+
+Without ``--stats``, borg will rely on the cached chunks index to determine
+existing object IDs (but there is no stored size information in the index,
+thus it can't compute before/after compaction size statistics).

docs/usage/create.rst.inc

@@ -19,7 +19,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                                          | paths to archive                                                                                                                                                                                  |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                        |
+    | **options**                                                                                                                                                                                                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-n``, ``--dry-run``                             | do not create a backup archive                                                                                                                                                                    |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -120,7 +120,7 @@ borg create
         paths to archive
 
 
-    optional arguments
+    options
         -n, --dry-run    do not create a backup archive
         -s, --stats     print statistics for the created archive
         --list          output verbose list of items (files, dirs, ...)
@@ -336,7 +336,7 @@ command and piping. If you do so, the first PATH argument is interpreted
 as command to execute and any further arguments are treated as arguments
 to the command::
 
-    borg create --content-from-command  --repo REPO ARCHIVE -- backup-vm --id myvm --stdout
+    borg create --content-from-command --repo REPO ARCHIVE -- backup-vm --id myvm --stdout
 
 ``--`` is used to ensure ``--id`` and ``--stdout`` are **not** considered
 arguments to ``borg`` but rather ``backup-vm``.

docs/usage/delete.rst.inc

@@ -17,7 +17,7 @@ borg delete
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``NAME``                                     | specify the archive name                                                                                                    |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                   |
+    | **options**                                                                                                                                                                                                                                              |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-n``, ``--dry-run``                        | do not change repository                                                                                                    |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -60,7 +60,7 @@ borg delete
         specify the archive name
 
 
-    optional arguments
+    options
         -n, --dry-run     do not change repository
         --list            output verbose list of archives
 

docs/usage/diff.rst.inc

@@ -21,7 +21,7 @@ borg diff
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths of items inside the archives to compare; patterns are supported            |
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                           |
+    | **options**                                                                                                                                                                      |
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
     |                                                       | ``--numeric-ids``                     | only consider numeric user and group identifiers                                 |
     +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
@@ -68,7 +68,7 @@ borg diff
         paths of items inside the archives to compare; patterns are supported
 
 
-    optional arguments
+    options
         --numeric-ids    only consider numeric user and group identifiers
         --same-chunker-params    Override check of chunker parameters.
         --sort     Sort the output lines by file path.

docs/usage/export-tar.rst.inc

@@ -21,7 +21,7 @@ borg export-tar
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                    |
+    | **options**                                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--tar-filter``                      | filter program to pipe data through                                                                       |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -64,7 +64,7 @@ borg export-tar
         paths to extract; patterns are supported
 
 
-    optional arguments
+    options
         --tar-filter         filter program to pipe data through
         --list               output verbose list of items (files, dirs, ...)
         --tar-format FMT     select tar format: BORG, PAX or GNU

docs/usage/extract.rst.inc

@@ -19,7 +19,7 @@ borg extract
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                    |
+    | **options**                                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--list``                            | output verbose list of items (files, dirs, ...)                                                           |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -72,7 +72,7 @@ borg extract
         paths to extract; patterns are supported
 
 
-    optional arguments
+    options
         --list            output verbose list of items (files, dirs, ...)
         -n, --dry-run     do not actually change any files
         --numeric-ids     only obey numeric user and group identifiers

docs/usage/help.rst.inc

@@ -97,6 +97,15 @@ Exclusions can be passed via the command line option ``--exclude``. When used
 from within a shell, the patterns should be quoted to protect them from
 expansion.
 
+Patterns matching special characters, e.g. white space, within a shell may 
+require adjustments, such as putting quotation marks around the arguments.
+Example: 
+Using bash, the following command line option would match and exclude "item name":
+``--pattern='-path/item name'``
+Note that when patterns are used within a pattern file directly read by borg,  
+e.g. when using ``--exclude-from`` or ``--patterns-from``, there is no shell 
+involved and thus no quotation marks are required.
+
 The ``--exclude-from`` option permits loading exclusion patterns from a text
 file with one pattern per line. Lines empty or starting with the hash sign
 '#' after removing whitespace on both ends are ignored. The optional style
@@ -357,12 +366,12 @@ and ``--remote-path`` values support these placeholders:
 
 If literal curly braces need to be used, double them for escaping::
 
-    borg create /path/to/repo::{{literal_text}}
+    borg create --repo /path/to/repo {{literal_text}}
 
 Examples::
 
-    borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
-    borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S%z} ...
+    borg create --repo /path/to/repo {hostname}-{user}-{utcnow} ...
+    borg create --repo /path/to/repo {hostname}-{now:%Y-%m-%d_%H:%M:%S%z} ...
     borg prune -a 'sh:{hostname}-*' ...
 
 .. note::
@@ -469,16 +478,26 @@ obfuscate,SPEC,C[,L]
       ...
       123: 8MiB (max.)
 
+    *Padmé padding* (deterministic)
+
+    ::
+
+      250: pads to sums of powers of 2, max 12% overhead
+
+    Uses the Padmé algorithm to deterministically pad the compressed size to a sum of
+    powers of 2, limiting overhead to 12%. See https://lbarman.ch/blog/padme/ for details.
+
 Examples::
 
-    borg create --compression lz4 REPO::ARCHIVE data
-    borg create --compression zstd REPO::ARCHIVE data
-    borg create --compression zstd,10 REPO::ARCHIVE data
-    borg create --compression zlib REPO::ARCHIVE data
-    borg create --compression zlib,1 REPO::ARCHIVE data
-    borg create --compression auto,lzma,6 REPO::ARCHIVE data
+    borg create --compression lz4 --repo REPO ARCHIVE data
+    borg create --compression zstd --repo REPO ARCHIVE data
+    borg create --compression zstd,10 --repo REPO ARCHIVE data
+    borg create --compression zlib --repo REPO ARCHIVE data
+    borg create --compression zlib,1 --repo REPO ARCHIVE data
+    borg create --compression auto,lzma,6 --repo REPO ARCHIVE data
     borg create --compression auto,lzma ...
     borg create --compression obfuscate,110,none ...
     borg create --compression obfuscate,3,auto,zstd,10 ...
     borg create --compression obfuscate,2,zstd,6 ...
+    borg create --compression obfuscate,250,zstd,3 ...
 

docs/usage/import-tar.rst.inc

@@ -19,7 +19,7 @@ borg import-tar
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``TARFILE``                                       | input tar file. "-" to read from stdin instead.                                                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                        |
+    | **options**                                                                                                                                                                                                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--tar-filter``                                  | filter program to pipe data through                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -64,7 +64,7 @@ borg import-tar
         input tar file. "-" to read from stdin instead.
 
 
-    optional arguments
+    options
         --tar-filter    filter program to pipe data through
         -s, --stats     print statistics for the created archive
         --list          output verbose list of items (files, dirs, ...)

docs/usage/info.rst.inc

@@ -17,7 +17,7 @@ borg info
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``NAME``                                     | specify the archive name                                                                                                    |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                   |
+    | **options**                                                                                                                                                                                                                                              |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--json``                                   | format output as JSON                                                                                                       |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -58,7 +58,7 @@ borg info
         specify the archive name
 
 
-    optional arguments
+    options
         --json     format output as JSON
 
 

docs/usage/key_change-location.rst.inc

@@ -17,7 +17,7 @@ borg key change-location
     +-------------------------------------------------------+------------------+----------------------------------------------------------------+
     |                                                       | ``KEY_LOCATION`` | select key location                                            |
     +-------------------------------------------------------+------------------+----------------------------------------------------------------+
-    | **optional arguments**                                                                                                                    |
+    | **options**                                                                                                                               |
     +-------------------------------------------------------+------------------+----------------------------------------------------------------+
     |                                                       | ``--keep``       | keep the key also at the current location (default: remove it) |
     +-------------------------------------------------------+------------------+----------------------------------------------------------------+
@@ -40,7 +40,7 @@ borg key change-location
         select key location
 
 
-    optional arguments
+    options
         --keep     keep the key also at the current location (default: remove it)
 
 

docs/usage/key_export.rst.inc

@@ -17,7 +17,7 @@ borg key export
     +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
     |                                                       | ``PATH``      | where to store the backup                                              |
     +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                         |
+    | **options**                                                                                                                                    |
     +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
     |                                                       | ``--paper``   | Create an export suitable for printing and later type-in               |
     +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
@@ -42,7 +42,7 @@ borg key export
         where to store the backup
 
 
-    optional arguments
+    options
         --paper       Create an export suitable for printing and later type-in
         --qr-html     Create an html file suitable for printing and later type-in or qr scan
 

docs/usage/key_import.rst.inc

@@ -17,7 +17,7 @@ borg key import
     +-------------------------------------------------------+-------------+----------------------------------------------------------+
     |                                                       | ``PATH``    | path to the backup ('-' to read from stdin)              |
     +-------------------------------------------------------+-------------+----------------------------------------------------------+
-    | **optional arguments**                                                                                                         |
+    | **options**                                                                                                                    |
     +-------------------------------------------------------+-------------+----------------------------------------------------------+
     |                                                       | ``--paper`` | interactively import from a backup done with ``--paper`` |
     +-------------------------------------------------------+-------------+----------------------------------------------------------+
@@ -40,7 +40,7 @@ borg key import
         path to the backup ('-' to read from stdin)
 
 
-    optional arguments
+    options
         --paper     interactively import from a backup done with ``--paper``
 
 

docs/usage/list.rst.inc

@@ -19,7 +19,7 @@ borg list
     +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths to list; patterns are supported                                                                                                                                                 |
     +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                |
+    | **options**                                                                                                                                                                                                                                                                           |
     +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--short``                           | only print file/directory names, nothing else                                                                                                                                         |
     +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -58,7 +58,7 @@ borg list
         paths to list; patterns are supported
 
 
-    optional arguments
+    options
         --short     only print file/directory names, nothing else
         --format FORMAT    specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}")
         --json-lines    Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text.
@@ -153,5 +153,3 @@ Keys available only when listing files in an archive:
 - archiveid: internal ID of the archive
 - archivename: name of the archive
 - extra: prepends {target} with " -> " for soft links and " link to " for hard links
-
-- health: either "healthy" (file ok) or "broken" (if file has all-zero replacement chunks)

docs/usage/mount.rst.inc

@@ -19,7 +19,7 @@ borg mount
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``PATH``                                     | paths to extract; patterns are supported                                                                                    |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                   |
+    | **options**                                                                                                                                                                                                                                              |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-f``, ``--foreground``                     | stay in foreground, do not daemonize                                                                                        |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -78,7 +78,7 @@ borg mount
         paths to extract; patterns are supported
 
 
-    optional arguments
+    options
         -f, --foreground    stay in foreground, do not daemonize
         -o     Extra mount options
         --numeric-ids    use numeric user and group identifiers from archive(s)
@@ -159,9 +159,9 @@ Additional mount options supported by borg:
 
 - ``versions``: when used with a repository mount, this gives a merged, versioned
   view of the files in the archives. EXPERIMENTAL, layout may change in future.
-- ``allow_damaged_files``: by default damaged files (where missing chunks were
-  replaced with runs of zeros by ``borg check --repair``) are not readable and
-  return EIO (I/O error). Set this option to read such files.
+- ``allow_damaged_files``: by default damaged files (where chunks are missing)
+  will return EIO (I/O error) when trying to read the related parts of the file.
+  Set this option to replace the missing parts with all-zero bytes.
 - ``ignore_permissions``: for security reasons the ``default_permissions`` mount
   option is internally enforced by borg. ``ignore_permissions`` can be given to
   not enforce ``default_permissions``.

docs/usage/prune.rst.inc

@@ -17,7 +17,7 @@ borg prune
     +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
     |                                                                             | ``NAME``                                     | specify the archive name                                                                          |
     +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                         |
+    | **options**                                                                                                                                                                                                                    |
     +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
     |                                                                             | ``-n``, ``--dry-run``                        | do not change repository                                                                          |
     +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
@@ -82,7 +82,7 @@ borg prune
         specify the archive name
 
 
-    optional arguments
+    options
         -n, --dry-run         do not change repository
         --list                output verbose list of archives it keeps/prunes
         --short               use a less wide archive part format
@@ -144,10 +144,9 @@ from different machines) in one shared repository, use one prune call per
 series.
 
 The ``--keep-within`` option takes an argument of the form "<int><char>",
-where char is "y", "m", "w", "d", "H", "M", or "S" and represents years, months, 
-weeks, days, hours, minutes or seconds.  For example, ``--keep-within 2d`` means
-to keep all archives that were created within the past 48 hours.
-"1m" is taken to mean "31d" and "1y" represents "365d". The archives kept with 
+where char is "y", "m", "w", "d", "H", "M", or "S".  For example,
+``--keep-within 2d`` means to keep all archives that were created within
+the past 2 days.  "1m" is taken to mean "31d". The archives kept with
 this option do not count towards the totals specified by any other options.
 
 A good procedure is to thin out more and more the older your backups get.
@@ -174,4 +173,4 @@ backup archive in the same second).
 
 You can influence how the ``--list`` output is formatted by using the ``--short``
 option (less wide output) or by giving a custom format using ``--format`` (see
-the ``borg repo-list`` description for more details about the format string).
+the ``borg repo-list`` description for more details about the format string).

docs/usage/recreate.rst.inc

@@ -17,7 +17,7 @@ borg recreate
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``PATH``                                          | paths to recreate; patterns are supported                                                                                                                                                         |
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                              |
+    | **options**                                                                                                                                                                                                                                                                                                                         |
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                                                                   |
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -90,7 +90,7 @@ borg recreate
         paths to recreate; patterns are supported
 
 
-    optional arguments
+    options
         --list          output verbose list of items (files, dirs, ...)
         --filter STATUSCHARS    only display items with the given status characters (listed in borg create --help)
         -n, --dry-run    do not change anything
@@ -163,13 +163,7 @@ When rechunking, space usage can be substantial - expect
 at least the entire deduplicated size of the archives using the previous
 chunker params.
 
-If you recently ran borg check --repair and it had to fix lost chunks with all-zero
-replacement chunks, please first run another backup for the same data and re-run
-borg check --repair afterwards to heal any archives that had lost chunks which are
-still generated from the input data.
-
-Important: running borg recreate to re-chunk will remove the chunks_healthy
-metadata of all items with replacement chunks, so healing will not be possible
-any more after re-chunking (it is also unlikely it would ever work: due to the
-change of chunking parameters, the missing chunk likely will never be seen again
-even if you still have the data that produced it).
+If your most recent borg check found missing chunks, please first run another
+backup for the same data, before doing any rechunking. If you are lucky, that
+will re-create the missing chunks. Optionally, do another borg check, to see
+if the chunks are still missing).

docs/usage/repo-compress.rst.inc

@@ -13,7 +13,7 @@ borg repo-compress
     .. class:: borg-options-table
 
     +-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                       |
+    | **options**                                                                                                                                                                                                  |
     +-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
     |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
     +-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
@@ -36,7 +36,7 @@ borg repo-compress
 
 
 
-    optional arguments
+    options
         -C COMPRESSION, --compression COMPRESSION    select compression algorithm, see the output of the "borg help compression" command for details.
         -s, --stats     print statistics
 

docs/usage/repo-create.rst.inc

@@ -13,7 +13,7 @@ borg repo-create
     .. class:: borg-options-table
 
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                              |
+    | **options**                                                                                                                                                                                                                                                                                                                         |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--other-repo SRC_REPOSITORY``    | reuse the key material from the other repository                                                                                                                                                                                       |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -25,8 +25,6 @@ borg repo-create
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--storage-quota QUOTA``          | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.                                                                                                                                                            |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--make-parent-dirs``             | create the parent directories of the repository directory, if they are missing.                                                                                                                                                        |
-    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--copy-crypt-key``               | copy the crypt_key (used for authenticated encryption) from the key of the other repo (default: new random key).                                                                                                                       |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                                                                      |
@@ -46,13 +44,12 @@ borg repo-create
 
 
 
-    optional arguments
+    options
         --other-repo SRC_REPOSITORY    reuse the key material from the other repository
         --from-borg1                   other repository is borg 1.x
         -e MODE, --encryption MODE     select encryption key mode **(required)**
         --append-only                  create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
         --storage-quota QUOTA          Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
-        --make-parent-dirs             create the parent directories of the repository directory, if they are missing.
         --copy-crypt-key               copy the crypt_key (used for authenticated encryption) from the key of the other repo (default: new random key).
 
 

docs/usage/repo-delete.rst.inc

@@ -13,7 +13,7 @@ borg repo-delete
     .. class:: borg-options-table
 
     +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                              |
+    | **options**                                                                                                                                                                         |
     +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
     |                                                       | ``-n``, ``--dry-run``    | do not change repository                                                                         |
     +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
@@ -42,7 +42,7 @@ borg repo-delete
 
 
 
-    optional arguments
+    options
         -n, --dry-run     do not change repository
         --list            output verbose list of archives
         --force           force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.

docs/usage/repo-info.rst.inc

@@ -13,7 +13,7 @@ borg repo-info
     .. class:: borg-options-table
 
     +-------------------------------------------------------+------------+-----------------------+
-    | **optional arguments**                                                                     |
+    | **options**                                                                                |
     +-------------------------------------------------------+------------+-----------------------+
     |                                                       | ``--json`` | format output as JSON |
     +-------------------------------------------------------+------------+-----------------------+
@@ -34,7 +34,7 @@ borg repo-info
 
 
 
-    optional arguments
+    options
         --json     format output as JSON
 
 

docs/usage/repo-list.rst.inc

@@ -13,7 +13,7 @@ borg repo-list
     .. class:: borg-options-table
 
     +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                       |
+    | **options**                                                                                                                                                                                                                                                                                                  |
     +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--short``                                  | only print the archive IDs, nothing else                                                                                                                                        |
     +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -58,7 +58,7 @@ borg repo-list
 
 
 
-    optional arguments
+    options
         --short     only print the archive IDs, nothing else
         --format FORMAT    specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}")
         --json      Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text.

docs/usage/repo-space.rst.inc

@@ -13,7 +13,7 @@ borg repo-space
     .. class:: borg-options-table
 
     +-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                            |
+    | **options**                                                                                                                                       |
     +-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
     |                                                       | ``--reserve SPACE`` | Amount of space to reserve (e.g. 100M, 1G). Default: 0.             |
     +-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
@@ -36,7 +36,7 @@ borg repo-space
 
 
 
-    optional arguments
+    options
         --reserve SPACE     Amount of space to reserve (e.g. 100M, 1G). Default: 0.
         --free              Free all reserved space. Don't forget to reserve space later again.
 

docs/usage/serve.rst.inc

@@ -13,7 +13,7 @@ borg serve
     .. class:: borg-options-table
 
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+    | **options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--restrict-to-path PATH``       | restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to point directly to a repository.                                                                                                                                                                                                                                      |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -40,7 +40,7 @@ borg serve
 
 
 
-    optional arguments
+    options
         --restrict-to-path PATH    restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to point directly to a repository.
         --restrict-to-repository PATH    restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
         --append-only             only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.

docs/usage/tag.rst.inc

@@ -17,7 +17,7 @@ borg tag
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``NAME``                                     | specify the archive name                                                                                                    |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                   |
+    | **options**                                                                                                                                                                                                                                              |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--set TAG``                                | set tags (can be given multiple times)                                                                                      |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -62,7 +62,7 @@ borg tag
         specify the archive name
 
 
-    optional arguments
+    options
         --set TAG     set tags (can be given multiple times)
         --add TAG     add tags (can be given multiple times)
         --remove TAG    remove tags (can be given multiple times)

docs/usage/transfer.rst.inc

@@ -13,7 +13,7 @@ borg transfer
     .. class:: borg-options-table
 
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+    | **options**                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-n``, ``--dry-run``                             | do not change repository, just check                                                                                                                                                                                                                                                                                      |
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -62,7 +62,7 @@ borg transfer
 
 
 
-    optional arguments
+    options
         -n, --dry-run     do not change repository, just check
         --other-repo SRC_REPOSITORY    transfer archives from the other repository
         --from-borg1      other repository is borg 1.x

docs/usage/undelete.rst.inc

@@ -17,7 +17,7 @@ borg undelete
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``NAME``                                     | specify the archive name                                                                                                    |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                   |
+    | **options**                                                                                                                                                                                                                                              |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-n``, ``--dry-run``                        | do not change repository                                                                                                    |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -60,7 +60,7 @@ borg undelete
         specify the archive name
 
 
-    optional arguments
+    options
         -n, --dry-run     do not change repository
         --list            output verbose list of archives