python setup.py build_man

docs/man/borg-benchmark-cpu.1

@@ -0,0 +1,53 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-BENCHMARK-CPU 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-benchmark-cpu \- Benchmark CPU bound operations.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.sp
+borg [common options] benchmark cpu [options]
+.SH DESCRIPTION
+.sp
+This command benchmarks misc. CPU bound borg operations.
+.sp
+It creates input data in memory, runs the operation and then displays throughput.
+To reduce outside influence on the timings, please make sure to run this with:
+\- an otherwise as idle as possible machine
+\- enough free memory so there will be no slow down due to paging activity
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-benchmark-crud.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-BENCHMARK-CRUD 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .SH SYNOPSIS
 .sp
 borg [common options] benchmark crud [options] REPOSITORY PATH

docs/man/borg-benchmark.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-BENCHMARK 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-benchmark \- benchmark command
 .
 .nr rst2man-indent-level 0
 .
@@ -27,12 +30,10 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-benchmark \- benchmark command
 .SH SYNOPSIS
 .nf
 borg [common options] benchmark crud ...
+borg [common options] benchmark cpu ...
 .fi
 .sp
 .SH DESCRIPTION
@@ -40,7 +41,7 @@ borg [common options] benchmark crud ...
 These commands do various benchmarks.
 .SH SEE ALSO
 .sp
-\fIborg\-common(1)\fP, \fIborg\-benchmark\-crud(1)\fP
+\fIborg\-common(1)\fP, \fIborg\-benchmark\-crud(1)\fP, \fIborg\-benchmark\-cpu(1)\fP
 .SH AUTHOR
 The Borg Collective
 .\" Generated by docutils manpage writer.

docs/man/borg-break-lock.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-BREAK-LOCK 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "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
 .sp
 borg [common options] break\-lock [options] [REPOSITORY]

docs/man/borg-check.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-CHECK 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-check \- Check repository consistency
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-check \- Check repository consistency
 .SH SYNOPSIS
 .sp
 borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
@@ -104,15 +104,18 @@ The archive checks can be time consuming; they can be skipped using the
 The \fB\-\-max\-duration\fP option can be used to split a long\-running repository check
 into multiple partial checks. After the given number of seconds the check is
 interrupted. The next partial check will continue where the previous one stopped,
-until the complete repository has been checked. Example: Assuming a full check took 7
+until the complete repository has been checked. Example: Assuming a complete check took 7
 hours, then running a daily check with \-\-max\-duration=3600 (1 hour) resulted in one
-full check per week.
+completed check per week.
 .sp
-Attention: Partial checks can only do way less checking than a full check (only the
-CRC32 checks on segment file entries are done), and cannot be combined with the
-\fB\-\-repair\fP option. Partial checks may therefore be useful only with very large
-repositories where a full check took too long. Doing a full repository check aborts a
-partial check; the next partial check will restart from the beginning.
+Attention: A partial \-\-repository\-only check can only do way less checking than a full
+\-\-repository\-only check: only the non\-cryptographic checksum checks on segment file
+entries are done, while a full \-\-repository\-only check would also do a repo index check.
+A partial check cannot be combined with the \fB\-\-repair\fP option. Partial checks
+may therefore be useful only with very large repositories where a full check would take
+too long.
+Doing a full repository check aborts a partial check; the next partial check will restart
+from the beginning.
 .sp
 The \fB\-\-verify\-data\fP option will perform a full integrity verification (as opposed to
 checking the CRC32 of the segment) of data, which means reading the data from the
@@ -132,19 +135,19 @@ repository or archive to check consistency of
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-repository\-only
+.B \-\-repository\-only
 only perform repository checks
 .TP
-.B  \-\-archives\-only
+.B \-\-archives\-only
 only perform archives checks
 .TP
-.B  \-\-verify\-data
+.B \-\-verify\-data
 perform cryptographic archive data integrity verification (conflicts with \fB\-\-repository\-only\fP)
 .TP
-.B  \-\-repair
+.B \-\-repair
 attempt to repair any inconsistencies found
 .TP
-.B  \-\-save\-space
+.B \-\-save\-space
 work slower, but using less space
 .TP
 .BI \-\-max\-duration \ SECONDS

docs/man/borg-common.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-COMMON 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-common \- Common options of Borg commands
 .
 .nr rst2man-indent-level 0
 .
@@ -27,52 +30,49 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-common \- Common options of Borg commands
 .SH SYNOPSIS
 .INDENT 0.0
 .TP
-.B  \-h\fP,\fB  \-\-help
+.B \-h\fP,\fB  \-\-help
 show this help message and exit
 .TP
-.B  \-\-critical
+.B \-\-critical
 work on log level CRITICAL
 .TP
-.B  \-\-error
+.B \-\-error
 work on log level ERROR
 .TP
-.B  \-\-warning
+.B \-\-warning
 work on log level WARNING (default)
 .TP
-.B  \-\-info\fP,\fB  \-v\fP,\fB  \-\-verbose
+.B \-\-info\fP,\fB  \-v\fP,\fB  \-\-verbose
 work on log level INFO
 .TP
-.B  \-\-debug
+.B \-\-debug
 enable debug output, work on log level DEBUG
 .TP
 .BI \-\-debug\-topic \ TOPIC
 enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
 .TP
-.B  \-p\fP,\fB  \-\-progress
+.B \-p\fP,\fB  \-\-progress
 show progress information
 .TP
-.B  \-\-iec
+.B \-\-iec
 format using IEC units (1KiB = 1024B)
 .TP
-.B  \-\-log\-json
+.B \-\-log\-json
 Output one JSON object per log line instead of formatted text.
 .TP
 .BI \-\-lock\-wait \ SECONDS
 wait at most SECONDS for acquiring a repository/cache lock (default: 1).
 .TP
-.B  \-\-bypass\-lock
+.B \-\-bypass\-lock
 Bypass locking mechanism
 .TP
-.B  \-\-show\-version
+.B \-\-show\-version
 show/log the borg version
 .TP
-.B  \-\-show\-rc
+.B \-\-show\-rc
 show/log the return code (rc)
 .TP
 .BI \-\-umask \ M
@@ -93,7 +93,7 @@ deprecated, use \fB\-\-upload\-buffer\fP instead
 .BI \-\-upload\-buffer \ UPLOAD_BUFFER
 set network upload buffer size in MiB. (default: 0=no buffer)
 .TP
-.B  \-\-consider\-part\-files
+.B \-\-consider\-part\-files
 treat part files like normal files (e.g. to list/extract them)
 .TP
 .BI \-\-debug\-profile \ FILE

docs/man/borg-compact.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-COMPACT 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-compact \- compact segment files in the repository
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-compact \- compact segment files in the repository
 .SH SYNOPSIS
 .sp
 borg [common options] compact [options] [REPOSITORY]
@@ -53,7 +53,8 @@ When using \fB\-\-verbose\fP, borg will output an estimate of the freed space.
 .sp
 After upgrading borg (server) to 1.2+, you can use \fBborg compact \-\-cleanup\-commits\fP
 to clean up the numerous 17byte commit\-only segments that borg 1.1 did not clean up
-due to a bug. It is enough to do that once per repository.
+due to a bug. It is enough to do that once per repository. After cleaning up the
+commits, borg will also do a normal compaction.
 .sp
 See \fIseparate_compaction\fP in Additional Notes for more details.
 .SH OPTIONS
@@ -68,7 +69,7 @@ repository to compact
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-cleanup\-commits
+.B \-\-cleanup\-commits
 cleanup commit\-only 17\-byte segment files
 .TP
 .BI \-\-threshold \ PERCENT

docs/man/borg-compression.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-COMPRESSION 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-compression \- Details regarding compression
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-compression \- Details regarding compression
 .SH DESCRIPTION
 .sp
 It is no problem to mix different compression methods in one repo,

docs/man/borg-config.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-CONFIG 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-config \- get, set, and delete values in a repository or cache config file
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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-CONFIG" 1 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-config \- get, set, and delete values in a repository or cache config file
 .SH SYNOPSIS
 .sp
 borg [common options] config [options] [REPOSITORY] [NAME] [VALUE]
@@ -65,13 +65,13 @@ new value for key
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-c\fP,\fB  \-\-cache
+.B \-c\fP,\fB  \-\-cache
 get and set values from the repo cache
 .TP
-.B  \-d\fP,\fB  \-\-delete
+.B \-d\fP,\fB  \-\-delete
 delete the key from the config file
 .TP
-.B  \-l\fP,\fB  \-\-list
+.B \-l\fP,\fB  \-\-list
 list the configuration of the repo
 .UNINDENT
 .SH EXAMPLES

docs/man/borg-create.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-CREATE 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-create \- Create new archive
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-create \- Create new archive
 .SH SYNOPSIS
 .sp
 borg [common options] create [options] ARCHIVE [PATH...]
@@ -135,22 +135,22 @@ paths to archive
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-n\fP,\fB  \-\-dry\-run
+.B \-n\fP,\fB  \-\-dry\-run
 do not create a backup archive
 .TP
-.B  \-s\fP,\fB  \-\-stats
+.B \-s\fP,\fB  \-\-stats
 print statistics for the created archive
 .TP
-.B  \-\-list
+.B \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
 .BI \-\-filter \ STATUSCHARS
 only display items with the given status characters (see description)
 .TP
-.B  \-\-json
+.B \-\-json
 output stats as JSON. Implies \fB\-\-stats\fP\&.
 .TP
-.B  \-\-no\-cache\-sync
+.B \-\-no\-cache\-sync
 experimental: do not synchronize the cache. Implies not using the files cache.
 .TP
 .BI \-\-stdin\-name \ NAME
@@ -160,18 +160,18 @@ use NAME in archive for stdin data (default: \(aqstdin\(aq)
 set user USER in archive for stdin data (default: \(aqroot\(aq)
 .TP
 .BI \-\-stdin\-group \ GROUP
-set group GROUP in archive for stdin data (default: \(aqwheel\(aq)
+set group GROUP in archive for stdin data (default: \(aqroot\(aq)
 .TP
 .BI \-\-stdin\-mode \ M
 set mode to M in archive for stdin data (default: 0660)
 .TP
-.B  \-\-content\-from\-command
+.B \-\-content\-from\-command
 interpret PATH as command and store its stdout. See also section Reading from stdin below.
 .TP
-.B  \-\-paths\-from\-stdin
+.B \-\-paths\-from\-stdin
 read DELIM\-separated list of paths to backup from stdin. Will not recurse into directories.
 .TP
-.B  \-\-paths\-from\-command
+.B \-\-paths\-from\-command
 interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP
 .TP
 .BI \-\-paths\-delimiter \ DELIM
@@ -192,61 +192,61 @@ include/exclude paths matching PATTERN
 .BI \-\-patterns\-from \ PATTERNFILE
 read include/exclude patterns from PATTERNFILE, one per line
 .TP
-.B  \-\-exclude\-caches
+.B \-\-exclude\-caches
 exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
 .TP
-.B  \-\-keep\-exclude\-tags
+.B \-\-keep\-exclude\-tags
 if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive
 .TP
-.B  \-\-exclude\-nodump
+.B \-\-exclude\-nodump
 exclude files flagged NODUMP
 .UNINDENT
 .SS Filesystem options
 .INDENT 0.0
 .TP
-.B  \-x\fP,\fB  \-\-one\-file\-system
+.B \-x\fP,\fB  \-\-one\-file\-system
 stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs.
 .TP
-.B  \-\-numeric\-owner
+.B \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
 .TP
-.B  \-\-numeric\-ids
+.B \-\-numeric\-ids
 only store numeric user and group identifiers
 .TP
-.B  \-\-noatime
+.B \-\-noatime
 do not store atime into archive
 .TP
-.B  \-\-atime
+.B \-\-atime
 do store atime into archive
 .TP
-.B  \-\-noctime
+.B \-\-noctime
 do not store ctime into archive
 .TP
-.B  \-\-nobirthtime
+.B \-\-nobirthtime
 do not store birthtime (creation date) into archive
 .TP
-.B  \-\-nobsdflags
+.B \-\-nobsdflags
 deprecated, use \fB\-\-noflags\fP instead
 .TP
-.B  \-\-noflags
+.B \-\-noflags
 do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive
 .TP
-.B  \-\-noacls
+.B \-\-noacls
 do not read and store ACLs into archive
 .TP
-.B  \-\-noxattrs
+.B \-\-noxattrs
 do not read and store xattrs into archive
 .TP
-.B  \-\-sparse
+.B \-\-sparse
 detect sparse holes in input (supported only by fixed chunker)
 .TP
 .BI \-\-files\-cache \ MODE
 operate files cache in MODE. default: ctime,size,inode
 .TP
-.B  \-\-read\-special
+.B \-\-read\-special
 open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
 .UNINDENT
 .SS Archive options

docs/man/borg-delete.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-DELETE 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-delete \- Delete an existing repository or archives
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-delete \- Delete an existing repository or archives
 .SH SYNOPSIS
 .sp
 borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...]
@@ -76,25 +76,25 @@ archives to delete
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-n\fP,\fB  \-\-dry\-run
+.B \-n\fP,\fB  \-\-dry\-run
 do not change repository
 .TP
-.B  \-\-list
+.B \-\-list
 output verbose list of archives
 .TP
-.B  \-s\fP,\fB  \-\-stats
+.B \-s\fP,\fB  \-\-stats
 print statistics for the deleted archive
 .TP
-.B  \-\-cache\-only
+.B \-\-cache\-only
 delete only the local cache for the given repository
 .TP
-.B  \-\-force
+.B \-\-force
 force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
 .TP
-.B  \-\-keep\-security\-info
+.B \-\-keep\-security\-info
 keep the local security info when deleting a repository
 .TP
-.B  \-\-save\-space
+.B \-\-save\-space
 work slower, but using less space
 .UNINDENT
 .SS Archive filters

docs/man/borg-diff.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-DIFF 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-diff \- Diff contents of two archives
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-diff \- Diff contents of two archives
 .SH SYNOPSIS
 .sp
 borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
@@ -69,19 +69,19 @@ paths of items inside the archives to compare; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-numeric\-owner
+.B \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
 .TP
-.B  \-\-numeric\-ids
+.B \-\-numeric\-ids
 only consider numeric user and group identifiers
 .TP
-.B  \-\-same\-chunker\-params
+.B \-\-same\-chunker\-params
 Override check of chunker parameters.
 .TP
-.B  \-\-sort
+.B \-\-sort
 Sort the output lines by file path.
 .TP
-.B  \-\-json\-lines
+.B \-\-json\-lines
 Format output as JSON Lines.
 .UNINDENT
 .SS Exclusion options

docs/man/borg-export-tar.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-EXPORT-TAR 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-export-tar \- Export archive contents as a tarball
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS
 .sp
 borg [common options] export\-tar [options] ARCHIVE FILE [PATH...]
@@ -59,12 +59,45 @@ Alternatively, a \fB\-\-tar\-filter\fP program may be explicitly specified. It s
 read the uncompressed tar stream from stdin and write a compressed/filtered
 tar stream to stdout.
 .sp
-The generated tarball uses the GNU tar format.
-.sp
-export\-tar is a lossy conversion:
-BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported.
-Timestamp resolution is limited to whole seconds, not the nanosecond resolution
-otherwise supported by Borg.
+Depending on the \fB\-tar\-format\fP option, these formats are created:
+.TS
+center;
+|l|l|l|.
+_
+T{
+\-\-tar\-format
+T}	T{
+Specification
+T}	T{
+Metadata
+T}
+_
+T{
+BORG
+T}	T{
+BORG specific, like PAX
+T}	T{
+all as supported by borg
+T}
+_
+T{
+PAX
+T}	T{
+POSIX.1\-2001 (pax) format
+T}	T{
+GNU + atime/ctime/mtime ns
+T}
+_
+T{
+GNU
+T}	T{
+GNU tar format
+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.
 .sp
@@ -94,11 +127,14 @@ paths to extract; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-tar\-filter
+.B \-\-tar\-filter
 filter program to pipe data through
 .TP
-.B  \-\-list
+.B \-\-list
 output verbose list of items (files, dirs, ...)
+.TP
+.BI \-\-tar\-format \ FMT
+select tar format: BORG, PAX or GNU
 .UNINDENT
 .SS Exclusion options
 .INDENT 0.0
@@ -118,31 +154,6 @@ read include/exclude patterns from PATTERNFILE, one per line
 .BI \-\-strip\-components \ NUMBER
 Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
 .UNINDENT
-.SH EXAMPLES
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# export as uncompressed tar
-$ borg export\-tar /path/to/repo::Monday Monday.tar
-
-# exclude some types, compress using gzip
-$ borg export\-tar /path/to/repo::Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq
-
-# use higher compression level with gzip
-$ borg export\-tar \-\-tar\-filter="gzip \-9" testrepo::linux Monday.tar.gz
-
-# export a tar, but instead of storing it on disk,
-# upload it to a remote site using curl.
-$ borg export\-tar /path/to/repo::Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST
-
-# remote extraction via "tarpipe"
-$ borg export\-tar /path/to/repo::Monday \- | ssh somewhere "cd extracted; tar x"
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP

docs/man/borg-extract.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-EXTRACT 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-extract \- Extract archive contents
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-extract \- Extract archive contents
 .SH SYNOPSIS
 .sp
 borg [common options] extract [options] ARCHIVE [PATH...]
@@ -75,34 +75,34 @@ paths to extract; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-list
+.B \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
-.B  \-n\fP,\fB  \-\-dry\-run
+.B \-n\fP,\fB  \-\-dry\-run
 do not actually change any files
 .TP
-.B  \-\-numeric\-owner
+.B \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
 .TP
-.B  \-\-numeric\-ids
+.B \-\-numeric\-ids
 only obey numeric user and group identifiers
 .TP
-.B  \-\-nobsdflags
+.B \-\-nobsdflags
 deprecated, use \fB\-\-noflags\fP instead
 .TP
-.B  \-\-noflags
+.B \-\-noflags
 do not extract/set flags (e.g. NODUMP, IMMUTABLE)
 .TP
-.B  \-\-noacls
+.B \-\-noacls
 do not extract/set ACLs
 .TP
-.B  \-\-noxattrs
+.B \-\-noxattrs
 do not extract/set xattrs
 .TP
-.B  \-\-stdout
+.B \-\-stdout
 write all extracted data to stdout
 .TP
-.B  \-\-sparse
+.B \-\-sparse
 create holes in output sparse file from all\-zero chunks
 .UNINDENT
 .SS Exclusion options

docs/man/borg-import-tar.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-IMPORT-TAR 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-import-tar \- Create a backup archive from a tarball
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-import-tar \- Create a backup archive from a tarball
 .SH SYNOPSIS
 .sp
 borg [common options] import\-tar [options] ARCHIVE TARFILE
@@ -61,15 +61,25 @@ stdout.
 Most documentation of borg create applies. Note that this command does not
 support excluding files.
 .sp
-import\-tar is a lossy conversion:
-BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported.
-Timestamp resolution is limited to whole seconds, not the nanosecond resolution
-otherwise supported by Borg.
-.sp
 A \fB\-\-sparse\fP option (as found in borg create) is not supported.
 .sp
-import\-tar reads POSIX.1\-1988 (ustar), POSIX.1\-2001 (pax), GNU tar, UNIX V7 tar
-and SunOS tar with extended attributes.
+About tar formats and metadata conservation or loss, please see \fBborg export\-tar\fP\&.
+.sp
+import\-tar reads these tar formats:
+.INDENT 0.0
+.IP \(bu 2
+BORG: borg specific (PAX\-based)
+.IP \(bu 2
+PAX: POSIX.1\-2001
+.IP \(bu 2
+GNU: GNU tar
+.IP \(bu 2
+POSIX.1\-1988 (ustar)
+.IP \(bu 2
+UNIX V7 tar
+.IP \(bu 2
+SunOS tar with extended attributes
+.UNINDENT
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -85,19 +95,19 @@ input tar file. "\-" to read from stdin instead.
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-tar\-filter
+.B \-\-tar\-filter
 filter program to pipe data through
 .TP
-.B  \-s\fP,\fB  \-\-stats
+.B \-s\fP,\fB  \-\-stats
 print statistics for the created archive
 .TP
-.B  \-\-list
+.B \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
 .BI \-\-filter \ STATUSCHARS
 only display items with the given status characters
 .TP
-.B  \-\-json
+.B \-\-json
 output stats as JSON (implies \-\-stats)
 .UNINDENT
 .SS Archive options
@@ -118,6 +128,80 @@ specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BI
 .BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
 select compression algorithm, see the output of the "borg help compression" command for details.
 .UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# export as uncompressed tar
+$ borg export\-tar /path/to/repo::Monday Monday.tar
+
+# import an uncompressed tar
+$ borg import\-tar /path/to/repo::Monday Monday.tar
+
+# exclude some file types, compress using gzip
+$ borg export\-tar /path/to/repo::Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq
+
+# use higher compression level with gzip
+$ borg export\-tar \-\-tar\-filter="gzip \-9" repo::Monday Monday.tar.gz
+
+# copy an archive from repoA to repoB
+$ borg export\-tar \-\-tar\-format=BORG repoA::archive \- | borg import\-tar repoB::archive \-
+
+# export a tar, but instead of storing it on disk, upload it to remote site using curl
+$ borg export\-tar /path/to/repo::Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST
+
+# remote extraction via "tarpipe"
+$ borg export\-tar /path/to/repo::Monday \- | ssh somewhere "cd extracted; tar x"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Archives transfer script
+.sp
+Outputs a script that copies all archives from repo1 to repo2:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+for A T in \(gaborg list \-\-format=\(aq{archive} {time:%Y\-%m\-%dT%H:%M:%S}{LF}\(aq repo1\(ga
+do
+  echo "borg export\-tar \-\-tar\-format=BORG repo1::$A \- | borg import\-tar \-\-timestamp=$T repo2::$A \-"
+done
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Kept:
+.INDENT 0.0
+.IP \(bu 2
+archive name, archive timestamp
+.IP \(bu 2
+archive contents (all items with metadata and data)
+.UNINDENT
+.sp
+Lost:
+.INDENT 0.0
+.IP \(bu 2
+some archive metadata (like the original commandline, execution time, etc.)
+.UNINDENT
+.sp
+Please note:
+.INDENT 0.0
+.IP \(bu 2
+all data goes over that pipe, again and again for every archive
+.IP \(bu 2
+the pipe is dumb, there is no data or transfer time reduction there due to deduplication
+.IP \(bu 2
+maybe add compression
+.IP \(bu 2
+pipe over ssh for remote transfer
+.IP \(bu 2
+no special sparse file support
+.UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP

docs/man/borg-info.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-INFO 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-info \- Show archive details such as disk space used
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS
 .sp
 borg [common options] info [options] [REPOSITORY_OR_ARCHIVE]
@@ -62,7 +62,7 @@ repository or archive to display information about
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-json
+.B \-\-json
 format output as JSON
 .UNINDENT
 .SS Archive filters

docs/man/borg-init.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-INIT 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-init \- Initialize an empty repository
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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-INIT" 1 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-init \- Initialize an empty repository
 .SH SYNOPSIS
 .sp
 borg [common options] init [options] [REPOSITORY]
@@ -39,11 +39,10 @@ This command initializes an empty repository. A repository is a filesystem
 directory containing the deduplicated data from zero or more archives.
 .SS Encryption mode TLDR
 .sp
-The encryption mode can only be configured when creating a new repository \-
-you can neither configure it on a per\-archive basis nor change the
-encryption mode of an existing repository.
-.sp
-Use \fBrepokey\fP:
+The encryption mode can only be configured when creating a new repository \- you can
+neither configure it on a per\-archive basis nor change the mode of an existing repository.
+This example will likely NOT give optimum performance on your machine (performance
+tips will come below):
 .INDENT 0.0
 .INDENT 3.5
 .sp
@@ -55,30 +54,20 @@ borg init \-\-encryption repokey /path/to/repo
 .UNINDENT
 .UNINDENT
 .sp
-Or \fBrepokey\-blake2\fP depending on which is faster on your client machines (see below):
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-borg init \-\-encryption repokey\-blake2 /path/to/repo
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
 Borg will:
 .INDENT 0.0
 .IP 1. 3
 Ask you to come up with a passphrase.
 .IP 2. 3
-Create a borg key (which contains 3 random secrets. See \fIkey_files\fP).
+Create a borg key (which contains some random secrets. See \fIkey_files\fP).
 .IP 3. 3
-Encrypt the key with your passphrase.
+Derive a "key encryption key" from your passphrase
 .IP 4. 3
+Encrypt and sign the key with the key encryption key
+.IP 5. 3
 Store the encrypted borg key inside the repository directory (in the repo config).
 This is why it is essential to use a secure passphrase.
-.IP 5. 3
+.IP 6. 3
 Encrypt and sign your backups to prevent anyone from reading or forging them unless they
 have the key and know the passphrase. Make sure to keep a backup of
 your key \fBoutside\fP the repository \- do not lock yourself out by
@@ -87,7 +76,7 @@ For remote backups the encryption is done locally \- the remote machine
 never sees your passphrase, your unencrypted key or your unencrypted files.
 Chunking and id generation are also based on your key to improve
 your privacy.
-.IP 6. 3
+.IP 7. 3
 Use the key when extracting files to decrypt them and to verify that the contents of
 the backups have not been accidentally or maliciously altered.
 .UNINDENT
@@ -113,107 +102,176 @@ a different keyboard layout.
 .sp
 You can change your passphrase for existing repos at any time, it won\(aqt affect
 the encryption/decryption key or other secrets.
-.SS More encryption modes
+.SS Choosing an encryption mode
 .sp
-Only use \fB\-\-encryption none\fP if you are OK with anyone who has access to
-your repository being able to read your backups and tamper with their
-contents without you noticing.
+Depending on your hardware, hashing and crypto performance may vary widely.
+The easiest way to find out about what\(aqs fastest is to run \fBborg benchmark cpu\fP\&.
 .sp
-If you want "passphrase and having\-the\-key" security, use \fB\-\-encryption keyfile\fP\&.
-The key will be stored in your home directory (in \fB~/.config/borg/keys\fP).
+\fIrepokey\fP modes: if you want ease\-of\-use and "passphrase" security is good enough \-
+the key will be stored in the repository (in \fBrepo_dir/config\fP).
 .sp
-If you do \fBnot\fP want to encrypt the contents of your backups, but still
-want to detect malicious tampering use \fB\-\-encryption authenticated\fP\&.
+\fIkeyfile\fP modes: if you rather want "passphrase and having\-the\-key" security \-
+the key will be stored in your home directory (in \fB~/.config/borg/keys\fP).
 .sp
-If \fBBLAKE2b\fP is faster than \fBSHA\-256\fP on your hardware, use \fB\-\-encryption authenticated\-blake2\fP,
-\fB\-\-encryption repokey\-blake2\fP or \fB\-\-encryption keyfile\-blake2\fP\&. Note: for remote backups
-the hashing is done on your local machine.
+The following table is roughly sorted in order of preference, the better ones are
+in the upper part of the table, in the lower part is the old and/or unsafe(r) stuff:
 .\" nanorst: inline-fill
 .
 .TS
 center;
-|l|l|l|l|.
+|l|l|l|l|l|.
 _
 T{
-Hash/MAC
+\fBmode (* = keyfile or repokey)\fP
 T}	T{
-Not encrypted
-no auth
+\fBID\-Hash\fP
 T}	T{
-Not encrypted,
-but authenticated
+\fBEncryption\fP
 T}	T{
-Encrypted (AEAD w/ AES)
-and authenticated
+\fBAuthentication\fP
+T}	T{
+\fBV>=\fP
 T}
 _
 T{
-SHA\-256
+\fB*\-blake2\-chacha20\-poly1305\fP
 T}	T{
-none
+BLAKE2b
+T}	T{
+CHACHA20
+T}	T{
+POLY1305
+T}	T{
+1.3
+T}
+_
+T{
+\fB*\-chacha20\-poly1305\fP
+T}	T{
+HMAC\-SHA\-256
+T}	T{
+CHACHA20
+T}	T{
+POLY1305
+T}	T{
+1.3
+T}
+_
+T{
+\fB*\-blake2\-aes\-ocb\fP
+T}	T{
+BLAKE2b
+T}	T{
+AES256\-OCB
+T}	T{
+AES256\-OCB
+T}	T{
+1.3
+T}
+_
+T{
+\fB*\-aes\-ocb\fP
+T}	T{
+HMAC\-SHA\-256
+T}	T{
+AES256\-OCB
+T}	T{
+AES256\-OCB
+T}	T{
+1.3
+T}
+_
+T{
+\fB*\-blake2\fP
+T}	T{
+BLAKE2b
+T}	T{
+AES256\-CTR
+T}	T{
+BLAKE2b
+T}	T{
+1.1
+T}
+_
+T{
+\fB*\fP
+T}	T{
+HMAC\-SHA\-256
+T}	T{
+AES256\-CTR
 T}	T{
-\fIauthenticated\fP
+HMAC\-SHA256
 T}	T{
-repokey
-keyfile
+any
 T}
 _
 T{
+authenticated\-blake2
+T}	T{
+BLAKE2b
+T}	T{
+none
+T}	T{
 BLAKE2b
 T}	T{
-n/a
+1.1
+T}
+_
+T{
+authenticated
+T}	T{
+HMAC\-SHA\-256
 T}	T{
-\fIauthenticated\-blake2\fP
+none
+T}	T{
+HMAC\-SHA256
 T}	T{
-\fIrepokey\-blake2\fP
-\fIkeyfile\-blake2\fP
+1.1
+T}
+_
+T{
+none
+T}	T{
+SHA\-256
+T}	T{
+none
+T}	T{
+none
+T}	T{
+any
 T}
 _
 .TE
 .\" nanorst: inline-replace
 .
 .sp
-Modes \fImarked like this\fP in the above table are new in Borg 1.1 and are not
-backwards\-compatible with Borg 1.0.x.
-.sp
-On modern Intel/AMD CPUs (except very cheap ones), AES is usually
-hardware\-accelerated.
-BLAKE2b is faster than SHA256 on Intel/AMD 64\-bit CPUs
-(except AMD Ryzen and future CPUs with SHA extensions),
-which makes \fIauthenticated\-blake2\fP faster than \fInone\fP and \fIauthenticated\fP\&.
-.sp
-On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
-than BLAKE2b\-256 there. NEON accelerates AES as well.
+\fInone\fP mode uses no encryption and no authentication. You\(aqre advised to NOT use this mode
+as it would expose you to all sorts of issues (DoS, confidentiality, tampering, ...) in
+case of malicious activity in the repository.
 .sp
-Hardware acceleration is always used automatically when available.
-.sp
-\fIrepokey\fP and \fIkeyfile\fP use AES\-CTR\-256 for encryption and HMAC\-SHA256 for
-authentication in an encrypt\-then\-MAC (EtM) construction. The chunk ID hash
-is HMAC\-SHA256 as well (with a separate key).
-These modes are compatible with Borg 1.0.x.
-.sp
-\fIrepokey\-blake2\fP and \fIkeyfile\-blake2\fP are also authenticated encryption modes,
-but use BLAKE2b\-256 instead of HMAC\-SHA256 for authentication. The chunk ID
-hash is a keyed BLAKE2b\-256 hash.
-These modes are new and \fInot\fP compatible with Borg 1.0.x.
-.sp
-\fIauthenticated\fP mode uses no encryption, but authenticates repository contents
-through the same HMAC\-SHA256 hash as the \fIrepokey\fP and \fIkeyfile\fP modes (it uses it
-as the chunk ID hash). The key is stored like \fIrepokey\fP\&.
-This mode is new and \fInot\fP compatible with Borg 1.0.x.
+If you do \fBnot\fP want to encrypt the contents of your backups, but still want to detect
+malicious tampering use an \fIauthenticated\fP mode. It\(aqs like \fIrepokey\fP minus encryption.
+.SS Key derivation functions
+.INDENT 0.0
+.IP \(bu 2
+\fB\-\-key\-algorithm argon2\fP is the default and is recommended.
+The key encryption key is derived from your passphrase via argon2\-id.
+Argon2 is considered more modern and secure than pbkdf2.
+.IP \(bu 2
+You can use \fB\-\-key\-algorithm pbkdf2\fP if you want to access your repo via old versions of borg.
+.UNINDENT
 .sp
-\fIauthenticated\-blake2\fP is like \fIauthenticated\fP, but uses the keyed BLAKE2b\-256 hash
-from the other blake2 modes.
-This mode is new and \fInot\fP compatible with Borg 1.0.x.
+Our implementation of argon2\-based key algorithm follows the cryptographic best practices:
+.INDENT 0.0
+.IP \(bu 2
+It derives two separate keys from your passphrase: one to encrypt your key and another one
+to sign it. \fB\-\-key\-algorithm pbkdf2\fP uses the same key for both.
+.IP \(bu 2
+It uses encrypt\-then\-mac instead of encrypt\-and\-mac used by \fB\-\-key\-algorithm pbkdf2\fP
+.UNINDENT
 .sp
-\fInone\fP mode uses no encryption and no authentication. It uses SHA256 as chunk
-ID hash. This mode is not recommended, you should rather consider using an authenticated
-or authenticated/encrypted mode. This mode has possible denial\-of\-service issues
-when running \fBborg create\fP on contents controlled by an attacker.
-Use it only for new repositories where no encryption is wanted \fBand\fP when compatibility
-with 1.0.x is important. If compatibility with 1.0.x is not important, use
-\fIauthenticated\-blake2\fP or \fIauthenticated\fP instead.
-This mode is compatible with Borg 1.0.x.
+Neither is inherently linked to the key derivation function, but since we were going
+to break backwards compatibility anyway we took the opportunity to fix all 3 issues at once.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -229,14 +287,17 @@ repository to create
 .BI \-e \ MODE\fR,\fB \ \-\-encryption \ MODE
 select encryption key mode \fB(required)\fP
 .TP
-.B  \-\-append\-only
+.B \-\-append\-only
 create an append\-only mode repository. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
 .TP
 .BI \-\-storage\-quota \ QUOTA
 Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
 .TP
-.B  \-\-make\-parent\-dirs
+.B \-\-make\-parent\-dirs
 create the parent directories of the repository directory, if they are missing.
+.TP
+.B \-\-key\-algorithm
+the algorithm we use to derive a key encryption key from your passphrase. Default: argon2
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
@@ -244,19 +305,22 @@ create the parent directories of the repository directory, if they are missing.
 .sp
 .nf
 .ft C
-# Local repository, repokey encryption, BLAKE2b (often faster, since Borg 1.1)
-$ borg init \-\-encryption=repokey\-blake2 /path/to/repo
+# Local repository, recommended repokey AEAD crypto modes
+$ borg init \-\-encryption=repokey\-aes\-ocb /path/to/repo
+$ borg init \-\-encryption=repokey\-chacha20\-poly1305 /path/to/repo
+$ borg init \-\-encryption=repokey\-blake2\-aes\-ocb /path/to/repo
+$ borg init \-\-encryption=repokey\-blake2\-chacha20\-poly1305 /path/to/repo
 
-# Local repository (no encryption)
+# Local repository (no encryption), not recommended
 $ borg init \-\-encryption=none /path/to/repo
 
 # Remote repository (accesses a remote borg via ssh)
 # repokey: stores the (encrypted) key into <REPO_DIR>/config
-$ borg init \-\-encryption=repokey\-blake2 user@hostname:backup
+$ borg init \-\-encryption=repokey\-aes\-ocb user@hostname:backup
 
 # Remote repository (accesses a remote borg via ssh)
 # keyfile: stores the (encrypted) key into ~/.config/borg/keys/
-$ borg init \-\-encryption=keyfile user@hostname:backup
+$ borg init \-\-encryption=keyfile\-aes\-ocb user@hostname:backup
 .ft P
 .fi
 .UNINDENT

docs/man/borg-key-change-algorithm.1

@@ -0,0 +1,93 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-KEY-CHANGE-ALGORITHM 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-key-change-algorithm \- Change repository key algorithm
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.sp
+borg [common options] key change\-algorithm [options] [REPOSITORY] ALGORITHM
+.SH DESCRIPTION
+.sp
+Change the algorithm we use to encrypt and authenticate the borg key.
+.sp
+Important: In a \fIrepokey\fP mode (e.g. repokey\-blake2) all users share the same key.
+In this mode upgrading to \fIargon2\fP will make it impossible to access the repo for users who use an old version of borg.
+We recommend upgrading to the latest stable version.
+.sp
+Important: In a \fIkeyfile\fP mode (e.g. keyfile\-blake2) each user has their own key (in \fB~/.config/borg/keys\fP).
+In this mode this command will only change the key used by the current user.
+If you want to upgrade to \fIargon2\fP to strengthen security, you will have to upgrade each user\(aqs key individually.
+.sp
+Your repository is encrypted and authenticated with a key that is randomly generated by \fBborg init\fP\&.
+The key is encrypted and authenticated with your passphrase.
+.sp
+We currently support two choices:
+.INDENT 0.0
+.IP 1. 3
+argon2 \- recommended. This algorithm is used by default when initialising a new repository.
+The key encryption key is derived from your passphrase via argon2\-id.
+Argon2 is considered more modern and secure than pbkdf2.
+.IP 2. 3
+pbkdf2 \- the legacy algorithm. Use this if you want to access your repo via old versions of borg.
+The key encryption key is derived from your passphrase via PBKDF2\-HMAC\-SHA256.
+.UNINDENT
+.sp
+Examples:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Upgrade an existing key to argon2
+borg key change\-algorithm /path/to/repo argon2
+# Downgrade to pbkdf2 \- use this if upgrading borg is not an option
+borg key change\-algorithm /path/to/repo pbkdf2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.sp
+REPOSITORY
+.INDENT 0.0
+.TP
+.B ALGORITHM
+select key algorithm
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-key-change-location.1

@@ -0,0 +1,70 @@
+.\" Man page generated from reStructuredText.
+.
+.TH BORG-KEY-CHANGE-LOCATION 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-key-change-location \- Change repository key location
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.sp
+borg [common options] key change\-location [options] [REPOSITORY] KEY_LOCATION
+.SH DESCRIPTION
+.sp
+Change the location of a borg key. The key can be stored at different locations:
+.sp
+keyfile: locally, usually in the home directory
+repokey: inside the repo (in the repo config)
+.INDENT 0.0
+.TP
+.B Note: this command does NOT change the crypto algorithms, just the key location,
+thus you must ONLY give the key location (keyfile or repokey).
+.UNINDENT
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.sp
+REPOSITORY
+.INDENT 0.0
+.TP
+.B KEY_LOCATION
+select key location
+.UNINDENT
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B \-\-keep
+keep the key also at the current location (default: remove it)
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-key-change-passphrase.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-key-change-passphrase \- Change repository key file passphrase
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-key-change-passphrase \- Change repository key file passphrase
 .SH SYNOPSIS
 .sp
 borg [common options] key change\-passphrase [options] [REPOSITORY]

docs/man/borg-key-export.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-KEY-EXPORT 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-key-export \- Export the repository key for backup
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-key-export \- Export the repository key for backup
 .SH SYNOPSIS
 .sp
 borg [common options] key export [options] [REPOSITORY] [PATH]
@@ -88,10 +88,10 @@ where to store the backup
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-paper
+.B \-\-paper
 Create an export suitable for printing and later type\-in
 .TP
-.B  \-\-qr\-html
+.B \-\-qr\-html
 Create an html file suitable for printing and later type\-in or qr scan
 .UNINDENT
 .SH SEE ALSO

docs/man/borg-key-import.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-KEY-IMPORT 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-key-import \- Import the repository key from backup
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-key-import \- Import the repository key from backup
 .SH SYNOPSIS
 .sp
 borg [common options] key import [options] [REPOSITORY] [PATH]
@@ -63,7 +63,7 @@ path to the backup (\(aq\-\(aq to read from stdin)
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-paper
+.B \-\-paper
 interactively import from a backup done with \fB\-\-paper\fP
 .UNINDENT
 .SH SEE ALSO

docs/man/borg-key.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-KEY 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-key \- Manage a keyfile or repokey of a repository
 .
 .nr rst2man-indent-level 0
 .
@@ -27,20 +30,18 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-key \- Manage a keyfile or repokey of a repository
 .SH SYNOPSIS
 .nf
 borg [common options] key export ...
 borg [common options] key import ...
 borg [common options] key change\-passphrase ...
-borg [common options] key migrate\-to\-repokey ...
+borg [common options] key change\-location ...
+borg [common options] key change\-algorithm ...
 .fi
 .sp
 .SH SEE ALSO
 .sp
-\fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP, \fIborg\-key\-migrate\-to\-repokey(1)\fP
+\fIborg\-common(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP, \fIborg\-key\-change\-location(1)\fP, \fIborg\-key\-change\-algorithm(1)\fP
 .SH AUTHOR
 The Borg Collective
 .\" Generated by docutils manpage writer.

docs/man/borg-list.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-LIST 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-list \- List archive or repository contents
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-list \- List archive or repository contents
 .SH SYNOPSIS
 .sp
 borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
@@ -53,19 +53,19 @@ paths to list; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-consider\-checkpoints
+.B \-\-consider\-checkpoints
 Show checkpoint archives in the repository contents list (default: hidden).
 .TP
-.B  \-\-short
+.B \-\-short
 only print file/directory names, nothing else
 .TP
 .BI \-\-format \ FORMAT
 specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}")
 .TP
-.B  \-\-json
+.B \-\-json
 Only valid for listing repository contents. Format output as JSON. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
 .TP
-.B  \-\-json\-lines
+.B \-\-json\-lines
 Only valid for listing archive contents. Format output as JSON Lines. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
 .UNINDENT
 .SS Archive filters

docs/man/borg-mount.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-MOUNT 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
 .sp
 borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
@@ -110,19 +110,19 @@ paths to extract; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-consider\-checkpoints
+.B \-\-consider\-checkpoints
 Show checkpoint archives in the repository contents list (default: hidden).
 .TP
-.B  \-f\fP,\fB  \-\-foreground
+.B \-f\fP,\fB  \-\-foreground
 stay in foreground, do not daemonize
 .TP
-.B  \-o
+.B \-o
 Extra mount options
 .TP
-.B  \-\-numeric\-owner
+.B \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
 .TP
-.B  \-\-numeric\-ids
+.B \-\-numeric\-ids
 use numeric user and group identifiers from archive(s)
 .UNINDENT
 .SS Archive filters

docs/man/borg-patterns.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-PATTERNS 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-patterns \- Details regarding patterns
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
 .sp
 The path/filenames used as input for the pattern matching start from the

docs/man/borg-placeholders.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-PLACEHOLDERS 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-placeholders \- Details regarding placeholders
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-placeholders \- Details regarding placeholders
 .SH DESCRIPTION
 .sp
 Repository (or Archive) URLs, \fB\-\-prefix\fP, \fB\-\-glob\-archives\fP, \fB\-\-comment\fP

docs/man/borg-prune.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-PRUNE 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-prune \- Prune repository archives according to specified rules
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS
 .sp
 borg [common options] prune [options] [REPOSITORY]
@@ -100,43 +100,43 @@ repository to prune
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-n\fP,\fB  \-\-dry\-run
+.B \-n\fP,\fB  \-\-dry\-run
 do not change repository
 .TP
-.B  \-\-force
+.B \-\-force
 force pruning of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
 .TP
-.B  \-s\fP,\fB  \-\-stats
+.B \-s\fP,\fB  \-\-stats
 print statistics for the deleted archive
 .TP
-.B  \-\-list
+.B \-\-list
 output verbose list of archives it keeps/prunes
 .TP
 .BI \-\-keep\-within \ INTERVAL
 keep all archives within this time interval
 .TP
-.B  \-\-keep\-last\fP,\fB  \-\-keep\-secondly
+.B \-\-keep\-last\fP,\fB  \-\-keep\-secondly
 number of secondly archives to keep
 .TP
-.B  \-\-keep\-minutely
+.B \-\-keep\-minutely
 number of minutely archives to keep
 .TP
-.B  \-H\fP,\fB  \-\-keep\-hourly
+.B \-H\fP,\fB  \-\-keep\-hourly
 number of hourly archives to keep
 .TP
-.B  \-d\fP,\fB  \-\-keep\-daily
+.B \-d\fP,\fB  \-\-keep\-daily
 number of daily archives to keep
 .TP
-.B  \-w\fP,\fB  \-\-keep\-weekly
+.B \-w\fP,\fB  \-\-keep\-weekly
 number of weekly archives to keep
 .TP
-.B  \-m\fP,\fB  \-\-keep\-monthly
+.B \-m\fP,\fB  \-\-keep\-monthly
 number of monthly archives to keep
 .TP
-.B  \-y\fP,\fB  \-\-keep\-yearly
+.B \-y\fP,\fB  \-\-keep\-yearly
 number of yearly archives to keep
 .TP
-.B  \-\-save\-space
+.B \-\-save\-space
 work slower, but using less space
 .UNINDENT
 .SS Archive filters

docs/man/borg-recreate.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-RECREATE 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-recreate \- Re-create archives
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-recreate \- Re-create archives
 .SH SYNOPSIS
 .sp
 borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
@@ -100,16 +100,16 @@ paths to recreate; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-\-list
+.B \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
 .BI \-\-filter \ STATUSCHARS
 only display items with the given status characters (listed in borg create \-\-help)
 .TP
-.B  \-n\fP,\fB  \-\-dry\-run
+.B \-n\fP,\fB  \-\-dry\-run
 do not change anything
 .TP
-.B  \-s\fP,\fB  \-\-stats
+.B \-s\fP,\fB  \-\-stats
 print statistics at end
 .UNINDENT
 .SS Exclusion options
@@ -127,13 +127,13 @@ include/exclude paths matching PATTERN
 .BI \-\-patterns\-from \ PATTERNFILE
 read include/exclude patterns from PATTERNFILE, one per line
 .TP
-.B  \-\-exclude\-caches
+.B \-\-exclude\-caches
 exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
 .TP
-.B  \-\-keep\-exclude\-tags
+.B \-\-keep\-exclude\-tags
 if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive
 .UNINDENT
 .SS Archive options

docs/man/borg-rename.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-RENAME 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-rename \- Rename an existing archive
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-rename \- Rename an existing archive
 .SH SYNOPSIS
 .sp
 borg [common options] rename [options] ARCHIVE NEWNAME

docs/man/borg-serve.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-SERVE 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-serve \- Start in server mode. This command is usually not used manually.
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-serve \- Start in server mode. This command is usually not used manually.
 .SH SYNOPSIS
 .sp
 borg [common options] serve [options]
@@ -48,7 +48,7 @@ restrict repository access to PATH. Can be specified multiple times to allow the
 .BI \-\-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 \fB\-\-restrict\-to\-path\fP sub\-directories are not accessible; PATH needs to directly point 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.
 .TP
-.B  \-\-append\-only
+.B \-\-append\-only
 only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
 .TP
 .BI \-\-storage\-quota \ QUOTA

docs/man/borg-umount.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-UMOUNT 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-umount \- un-mount the FUSE filesystem
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-umount \- un-mount the FUSE filesystem
 .SH SYNOPSIS
 .sp
 borg [common options] umount [options] MOUNTPOINT

docs/man/borg-upgrade.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-UPGRADE 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-upgrade \- upgrade a repository from a previous version
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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-UPGRADE" 1 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-upgrade \- upgrade a repository from a previous version
 .SH SYNOPSIS
 .sp
 borg [common options] upgrade [options] [REPOSITORY]
@@ -71,57 +71,16 @@ reverse the upgrade by issuing \fBborg upgrade \-\-disable\-tam REPO\fP\&.
 See
 \fI\%https://borgbackup.readthedocs.io/en/stable/changes.html#pre\-1\-0\-9\-manifest\-spoofing\-vulnerability\fP
 for details.
-.SS Attic and Borg 0.xx to Borg 1.x
+.SS Borg 0.xx to Borg 1.x
 .sp
-This currently supports converting an Attic repository to Borg and also
-helps with converting Borg 0.xx to 1.0.
+This currently supports converting Borg 0.xx to 1.0.
 .sp
 Currently, only LOCAL repositories can be upgraded (issue #465).
 .sp
 Please note that \fBborg create\fP (since 1.0.0) uses bigger chunks by
-default than old borg or attic did, so the new chunks won\(aqt deduplicate
+default than old borg did, so the new chunks won\(aqt deduplicate
 with the old chunks in the upgraded repository.
 See \fB\-\-chunker\-params\fP option of \fBborg create\fP and \fBborg recreate\fP\&.
-.sp
-\fBborg upgrade\fP will change the magic strings in the repository\(aqs
-segments to match the new Borg magic strings. The keyfiles found in
-$ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
-copied to $BORG_KEYS_DIR or ~/.config/borg/keys.
-.sp
-The cache files are converted, from $ATTIC_CACHE_DIR or
-~/.cache/attic to $BORG_CACHE_DIR or ~/.cache/borg, but the
-cache layout between Borg and Attic changed, so it is possible
-the first backup after the conversion takes longer than expected
-due to the cache resync.
-.sp
-Upgrade should be able to resume if interrupted, although it
-will still iterate over all segments. If you want to start
-from scratch, use \fIborg delete\fP over the copied repository to
-make sure the cache files are also removed:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-borg delete borg
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Unless \fB\-\-inplace\fP is specified, the upgrade process first creates a backup
-copy of the repository, in REPOSITORY.before\-upgrade\-DATETIME, using hardlinks.
-This requires that the repository and its parent directory reside on same
-filesystem so the hardlink copy can work.
-This takes longer than in place upgrades, but is much safer and gives
-progress information (as opposed to \fBcp \-al\fP). Once you are satisfied
-with the conversion, you can safely destroy the backup copy.
-.sp
-WARNING: Running the upgrade in place will make the current
-copy unusable with older version, with no way of going back
-to previous versions. This can PERMANENTLY DAMAGE YOUR
-REPOSITORY!  Attic CAN NOT READ BORG REPOSITORIES, as the
-magic strings have changed. You have been warned.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -134,19 +93,19 @@ path to the repository to be upgraded
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-n\fP,\fB  \-\-dry\-run
+.B \-n\fP,\fB  \-\-dry\-run
 do not change repository
 .TP
-.B  \-\-inplace
+.B \-\-inplace
 rewrite repository in place, with no chance of going back to older versions of the repository.
 .TP
-.B  \-\-force
+.B \-\-force
 Force upgrade
 .TP
-.B  \-\-tam
+.B \-\-tam
 Enable manifest authentication (in key and cache) (Borg 1.0.9 and later).
 .TP
-.B  \-\-disable\-tam
+.B \-\-disable\-tam
 Disable manifest authentication (in key and cache).
 .UNINDENT
 .SH EXAMPLES
@@ -168,20 +127,6 @@ no key file found for repository
 .fi
 .UNINDENT
 .UNINDENT
-.SS Upgrading a passphrase encrypted attic repo
-.sp
-attic offered a "passphrase" encryption mode, but this was removed in borg 1.0
-and replaced by the "repokey" mode (which stores the passphrase\-protected
-encryption key into the repository config).
-.sp
-Thus, to upgrade a "passphrase" attic repo to a "repokey" borg repo, 2 steps
-are needed, in this order:
-.INDENT 0.0
-.IP \(bu 2
-borg upgrade repo
-.IP \(bu 2
-borg key migrate\-to\-repokey repo
-.UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP

docs/man/borg-with-lock.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG-WITH-LOCK 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg-with-lock \- run a user specified command with the repository lock held
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg-with-lock \- run a user specified command with the repository lock held
 .SH SYNOPSIS
 .sp
 borg [common options] with\-lock [options] REPOSITORY COMMAND [ARGS...]

docs/man/borg.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORG 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borg \- deduplicating and encrypting backup tool
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS
 .sp
 borg [common options] <command> [options] [arguments]
@@ -162,7 +162,7 @@ $ borg extract /path/to/repo::Monday
 .UNINDENT
 .UNINDENT
 .IP 7. 3
-Recover disk space by manually deleting the \fIMonday\fP archive:
+Delete the \fIMonday\fP archive (please note that this does \fBnot\fP free repo disk space):
 .INDENT 3.0
 .INDENT 3.5
 .sp
@@ -173,6 +173,18 @@ $ borg delete /path/to/repo::Monday
 .fi
 .UNINDENT
 .UNINDENT
+.IP 8. 3
+Recover disk space by compacting the segment files in the repo:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg compact /path/to/repo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .UNINDENT
 .sp
 \fBNOTE:\fP
@@ -602,8 +614,7 @@ know a list of affected hardware.
 If you are suspicious whether your Borg repository is still consistent
 and readable after one of the failures mentioned above occurred, run
 \fBborg check \-\-verify\-data\fP to make sure it is consistent.
-Requirements for Borg repository file systems
-.INDENT 0.0
+Requirements for Borg repository file systems.INDENT 0.0
 .IP \(bu 2
 Long file names
 .IP \(bu 2

docs/man/borgfs.1

@@ -1,5 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
+.TH BORGFS 1 "2022-04-14" "" "borg backup tool"
+.SH NAME
+borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .
 .nr rst2man-indent-level 0
 .
@@ -27,9 +30,6 @@ 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 "2022-02-19" "" "borg backup tool"
-.SH NAME
-borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
 .sp
 borgfs [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
@@ -110,22 +110,22 @@ paths to extract; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B  \-V\fP,\fB  \-\-version
+.B \-V\fP,\fB  \-\-version
 show version number and exit
 .TP
-.B  \-\-consider\-checkpoints
+.B \-\-consider\-checkpoints
 Show checkpoint archives in the repository contents list (default: hidden).
 .TP
-.B  \-f\fP,\fB  \-\-foreground
+.B \-f\fP,\fB  \-\-foreground
 stay in foreground, do not daemonize
 .TP
-.B  \-o
+.B \-o
 Extra mount options
 .TP
-.B  \-\-numeric\-owner
+.B \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
 .TP
-.B  \-\-numeric\-ids
+.B \-\-numeric\-ids
 use numeric user and group identifiers from archive(s)
 .UNINDENT
 .SS Archive filters