Merge pull request #6930 from ThomasWaldmann/more-docs-updates

more docs updates

docs/internals/security.rst

@@ -83,7 +83,7 @@ authentication keys and calculating the HMAC of the metadata to authenticate [#]
     # RANDOM(n) returns n random bytes
     salt = RANDOM(64)
 
-    ikm = id_key || enc_key || enc_hmac_key
+    ikm = id_key || crypt_key
     # *context* depends on the operation, for manifest authentication it is
     # the ASCII string "borg-metadata-authentication-manifest".
     tam_key = HKDF-SHA-512(ikm, salt, context)

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CPU" 1 "2022-08-03" "" "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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CRUD" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .SH SYNOPSIS

docs/man/borg-benchmark.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BENCHMARK" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-BENCHMARK" 1 "2022-08-03" "" "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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" 1 "2022-08-03" "" "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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-CHECK" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .SH SYNOPSIS

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-COMMON" 1 "2022-08-03" "" "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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-COMPACT" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-compact \- compact segment files in the repository
 .SH SYNOPSIS

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-COMPRESSION" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .SH DESCRIPTION

docs/man/borg-config.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-CONFIG" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-CONFIG" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-config \- get, set, and delete values in a repository or cache config file
 .SH SYNOPSIS

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-CREATE" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .SH SYNOPSIS
@@ -297,7 +297,7 @@ $ fusermount \-u sshfs\-mount
 
 # Make a big effort in fine granular deduplication (big chunk management
 # overhead, needs a lot of RAM and disk space, see formula in internals
-# docs \- same parameters as borg < 1.0 or attic):
+# docs \- same parameters as borg < 1.0):
 $ borg create \-\-chunker\-params buzhash,10,23,16,4095 small /smallstuff
 
 # Backup a raw device (must not be active/in use/mounted at that time)

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-DELETE" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete archives
 .SH SYNOPSIS
@@ -76,11 +76,11 @@ delete only the local cache for the given repository
 .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
-keep the local security info when deleting a repository
-.TP
 .B  \-\-save\-space
 work slower, but using less space
+.TP
+.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
+write checkpoint every SECONDS seconds (Default: 1800)
 .UNINDENT
 .SS Archive filters
 .INDENT 0.0

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-DIFF" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .SH SYNOPSIS

docs/man/borg-export-tar.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-EXPORT-TAR" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS

docs/man/borg-extract.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-EXTRACT" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-EXTRACT" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .SH SYNOPSIS

docs/man/borg-import-tar.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-IMPORT-TAR" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-IMPORT-TAR" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-import-tar \- Create a backup archive from a tarball
 .SH SYNOPSIS

docs/man/borg-info.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-INFO" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-INFO" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS

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

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-CHANGE-LOCATION" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-LOCATION" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-key-change-location \- Change repository key location
 .SH SYNOPSIS

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

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .SH SYNOPSIS
@@ -52,7 +52,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .nf
 .ft C
 # Create a key file protected repository
-$ borg rcreate \-\-encryption=keyfile \-v
+$ borg rcreate \-\-encryption=keyfile\-aes\-ocb \-v
 Initializing repository at "/path/to/repo"
 Enter new passphrase:
 Enter same passphrase again:

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .SH SYNOPSIS

docs/man/borg-key-import.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-IMPORT" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-KEY-IMPORT" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .SH SYNOPSIS

docs/man/borg-key.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-KEY" 1 "2022-08-03" "" "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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-LIST" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive contents
 .SH SYNOPSIS

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-MOUNT" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-PATTERNS" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
@@ -220,7 +220,7 @@ pattern and would otherwise not be backed up.
 The first matching pattern is used, so if an include pattern matches
 before an exclude pattern, the file is backed up. Note that a no\-recurse
 exclude stops examination of subdirectories so that potential includes
-will not match \- use normal exludes for such use cases.
+will not match \- use normal excludes for such use cases.
 .sp
 \fBTip: You can easily test your patterns with \-\-dry\-run and  \-\-list\fP:
 .INDENT 0.0

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-PLACEHOLDERS" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .SH DESCRIPTION

docs/man/borg-prune.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-PRUNE" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-PRUNE" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS
@@ -132,6 +132,9 @@ number of yearly archives to keep
 .TP
 .B  \-\-save\-space
 work slower, but using less space
+.TP
+.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
+write checkpoint every SECONDS seconds (Default: 1800)
 .UNINDENT
 .SS Archive filters
 .INDENT 0.0

docs/man/borg-rcreate.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-RCREATE" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-RCREATE" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-rcreate \- Create a new, empty repository
 .SH SYNOPSIS
@@ -72,7 +72,7 @@ Encrypt and sign your backups to prevent anyone from reading or forging them unl
 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
 "leaving your keys inside your car" (see \fIborg_key_export\fP).
-For remote backups the encryption is done locally \- the remote machine
+The encryption is done locally \- if you use a remote repository, 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.
@@ -119,7 +119,7 @@ in the upper part of the table, in the lower part is the old and/or unsafe(r) st
 .
 .TS
 center;
-|l|l|l|l|l|.
+|l|l|l|l|.
 _
 T{
 Mode (K = keyfile or repokey)
@@ -129,8 +129,6 @@ T}	T{
 Encryption
 T}	T{
 Authentication
-T}	T{
-V >=
 T}
 _
 T{
@@ -141,8 +139,6 @@ T}	T{
 CHACHA20
 T}	T{
 POLY1305
-T}	T{
-2.0
 T}
 _
 T{
@@ -153,8 +149,6 @@ T}	T{
 CHACHA20
 T}	T{
 POLY1305
-T}	T{
-2.0
 T}
 _
 T{
@@ -165,8 +159,6 @@ T}	T{
 AES256\-OCB
 T}	T{
 AES256\-OCB
-T}	T{
-2.0
 T}
 _
 T{
@@ -177,32 +169,6 @@ T}	T{
 AES256\-OCB
 T}	T{
 AES256\-OCB
-T}	T{
-2.0
-T}
-_
-T{
-K\-blake2
-T}	T{
-BLAKE2b
-T}	T{
-AES256\-CTR
-T}	T{
-BLAKE2b
-T}	T{
-1.1
-T}
-_
-T{
-K
-T}	T{
-HMAC\-SHA\-256
-T}	T{
-AES256\-CTR
-T}	T{
-HMAC\-SHA256
-T}	T{
-any
 T}
 _
 T{
@@ -213,8 +179,6 @@ T}	T{
 none
 T}	T{
 BLAKE2b
-T}	T{
-1.1
 T}
 _
 T{
@@ -225,8 +189,6 @@ T}	T{
 none
 T}	T{
 HMAC\-SHA256
-T}	T{
-1.1
 T}
 _
 T{
@@ -237,8 +199,6 @@ T}	T{
 none
 T}	T{
 none
-T}	T{
-any
 T}
 _
 .TE
@@ -251,6 +211,18 @@ case of malicious activity in the repository.
 .sp
 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 Creating a related repository
+.sp
+A related repository uses same secret key material as the other/original repository.
+.sp
+By default, only the ID key and chunker secret will be the same (these are important
+for deduplication) and the AE crypto keys will be newly generated random keys.
+.sp
+Optionally, if you use \fB\-\-copy\-ae\-key\fP you can also keep the same AE crypto keys
+(used for authenticated encryption). Might be desired e.g. if you want to have less
+keys to manage.
+.sp
+Creating related repositories is useful e.g. if you want to use \fBborg transfer\fP later.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -271,6 +243,9 @@ 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\-ae\-key
+copy the authenticated encryption (AE) key from the key of the other repo (default: new random key).
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
@@ -287,6 +262,7 @@ $ borg rcreate \-\-encryption=repokey\-blake2\-aes\-ocb
 $ borg rcreate \-\-encryption=repokey\-blake2\-chacha20\-poly1305
 # no encryption, not recommended
 $ borg rcreate \-\-encryption=authenticated
+$ borg rcreate \-\-encryption=authenticated\-blake2
 $ borg rcreate \-\-encryption=none
 
 # Remote repository (accesses a remote borg via ssh)

docs/man/borg-rdelete.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-RDELETE" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-RDELETE" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-rdelete \- Delete a repository
 .SH SYNOPSIS

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-RECREATE" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .SH SYNOPSIS

docs/man/borg-rename.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-RENAME" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-RENAME" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .SH SYNOPSIS

docs/man/borg-rinfo.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-RINFO" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-RINFO" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-rinfo \- Show repository infos
 .SH SYNOPSIS

docs/man/borg-rlist.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-RLIST" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-RLIST" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-rlist \- List the archives contained in a repository
 .SH SYNOPSIS

docs/man/borg-serve.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-SERVE" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-SERVE" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .SH SYNOPSIS

docs/man/borg-transfer.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-TRANSFER" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-TRANSFER" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-transfer \- archives transfer from other repository, optionally upgrade data format
 .SH SYNOPSIS
@@ -44,9 +44,9 @@ Suggested use for general purpose archive transfer (not repo upgrades):
 .sp
 .nf
 .ft C
-# initialize DST_REPO reusing key material from SRC_REPO, so that
+# 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 init \-\-other\-repo=SRC_REPO \-\-encryption=DST_ENC
+borg \-\-repo=DST_REPO rcreate \-\-other\-repo=SRC_REPO \-\-encryption=DST_ENC
 
 # transfer archives from SRC_REPO to DST_REPO
 borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-dry\-run  # check what it would do
@@ -126,15 +126,15 @@ $ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 rcreate \e
        \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-e repokey\-blake2\-aes\-ocb
 
 # 2. Check what and how much it would transfer:
-$ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \e
+$ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e
        \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run
 
 # 3. Transfer (copy) archives from old repo into new repo (takes time and space!):
-$ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \e
+$ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e
        \-\-other\-repo ssh://borg2@borgbackup/./tests/b12
 
 # 4. Check if we have everything (same as 2.):
-$ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \e
+$ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e
        \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run
 .ft P
 .fi

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 "2022-07-17" "" "borg backup tool"
+.TH "BORG-UMOUNT" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .SH SYNOPSIS

docs/man/borg-with-lock.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-WITH-LOCK" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG-WITH-LOCK" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .SH SYNOPSIS

docs/man/borg.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORG" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS

docs/man/borgfs.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORGFS" 1 "2022-07-17" "" "borg backup tool"
+.TH "BORGFS" 1 "2022-08-03" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS

docs/usage/delete.rst.inc

@@ -12,39 +12,39 @@ borg delete
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-n``, ``--dry-run``                 | do not change repository                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--list``                            | output verbose list of archives                                                                  |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--consider-checkpoints``            | consider checkpoint archives for deletion (default: not considered).                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-s``, ``--stats``                   | print statistics for the deleted archive                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--cache-only``                      | delete only the local cache for the given repository                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--force``                           | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-security-info``              | keep the local security info when deleting a repository                                          |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--save-space``                      | work slower, but using less space                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                         |
-    |                                                                                                                                                                                                                        |
-    | :ref:`common_options`                                                                                                                                                                                                  |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                            |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns".        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-n``, ``--dry-run``                             | do not change repository                                                                         |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--list``                                        | output verbose list of archives                                                                  |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--consider-checkpoints``                        | consider checkpoint archives for deletion (default: not considered).                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-s``, ``--stats``                               | print statistics for the deleted archive                                                         |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--cache-only``                                  | delete only the local cache for the given repository                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--force``                                       | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--save-space``                                  | work slower, but using less space                                                                |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                           |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                     |
+    |                                                                                                                                                                                                                                    |
+    | :ref:`common_options`                                                                                                                                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB``             | only consider archive names matching the glob. sh: rules apply, see "borg help patterns".        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--sort-by KEYS``                                | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--first N``                                     | consider first N archives after other filters were applied                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--last N``                                      | consider last N archives after other filters were applied                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -65,8 +65,8 @@ borg delete
         -s, --stats     print statistics for the deleted archive
         --cache-only    delete only the local cache for the given repository
         --force         force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
-        --keep-security-info    keep the local security info when deleting a repository
         --save-space    work slower, but using less space
+        -c SECONDS, --checkpoint-interval SECONDS    write checkpoint every SECONDS seconds (Default: 1800)
 
 
     :ref:`common_options`

docs/usage/help.rst.inc

@@ -173,7 +173,7 @@ Include pattern prefix ``+``
 The first matching pattern is used, so if an include pattern matches
 before an exclude pattern, the file is backed up. Note that a no-recurse
 exclude stops examination of subdirectories so that potential includes
-will not match - use normal exludes for such use cases.
+will not match - use normal excludes for such use cases.
 
 **Tip: You can easily test your patterns with --dry-run and  --list**::
 

docs/usage/key.rst

@@ -11,7 +11,7 @@ Examples
 ::
 
     # Create a key file protected repository
-    $ borg rcreate --encryption=keyfile -v
+    $ borg rcreate --encryption=keyfile-aes-ocb -v
     Initializing repository at "/path/to/repo"
     Enter new passphrase:
     Enter same passphrase again:

docs/usage/key_migrate-to-repokey.rst.inc

@@ -1,60 +0,0 @@
-.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
-
-.. _borg_key_migrate-to-repokey:
-
-borg key migrate-to-repokey
----------------------------
-.. code-block:: none
-
-    borg [common options] key migrate-to-repokey [options] [REPOSITORY]
-
-.. only:: html
-
-    .. class:: borg-options-table
-
-    +-------------------------------------------------------+----------------+--+
-    | **positional arguments**                                                  |
-    +-------------------------------------------------------+----------------+--+
-    |                                                       | ``REPOSITORY`` |  |
-    +-------------------------------------------------------+----------------+--+
-    | .. class:: borg-common-opt-ref                                            |
-    |                                                                           |
-    | :ref:`common_options`                                                     |
-    +-------------------------------------------------------+----------------+--+
-
-    .. raw:: html
-
-        <script type='text/javascript'>
-        $(document).ready(function () {
-            $('.borg-options-table colgroup').remove();
-        })
-        </script>
-
-.. only:: latex
-
-    REPOSITORY
-
-
-
-    :ref:`common_options`
-        |
-
-Description
-~~~~~~~~~~~
-
-This command migrates a repository from passphrase mode (removed in Borg 1.0)
-to repokey mode.
-
-You will be first asked for the repository passphrase (to open it in passphrase
-mode). This is the same passphrase as you used to use for this repo before 1.0.
-
-It will then derive the different secrets from this passphrase.
-
-Then you will be asked for a new passphrase (twice, for safety). This
-passphrase will be used to protect the repokey (which contains these same
-secrets in encrypted form). You may use the same passphrase as you used to
-use, but you may also use a different one.
-
-After migrating to repokey mode, you can change the passphrase at any time.
-But please note: the secrets will always stay the same and they could always
-be derived from your (old) passphrase-mode passphrase.

docs/usage/prune.rst.inc

@@ -12,43 +12,45 @@ borg prune
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-n``, ``--dry-run``                 | do not change repository                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--force``                           | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-s``, ``--stats``                   | print statistics for the deleted archive                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--list``                            | output verbose list of archives it keeps/prunes                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-within INTERVAL``            | keep all archives within this time interval                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-last``, ``--keep-secondly``  | number of secondly archives to keep                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-minutely``                   | number of minutely archives to keep                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-H``, ``--keep-hourly``             | number of hourly archives to keep                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-d``, ``--keep-daily``              | number of daily archives to keep                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-w``, ``--keep-weekly``             | number of weekly archives to keep                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-m``, ``--keep-monthly``            | number of monthly archives to keep                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-y``, ``--keep-yearly``             | number of yearly archives to keep                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--save-space``                      | work slower, but using less space                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                        |
-    |                                                                                                                                                                                                                       |
-    | :ref:`common_options`                                                                                                                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                           |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns".       |
-    +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-n``, ``--dry-run``                             | do not change repository                                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--force``                                       | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-s``, ``--stats``                               | print statistics for the deleted archive                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--list``                                        | output verbose list of archives it keeps/prunes                                                 |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--keep-within INTERVAL``                        | keep all archives within this time interval                                                     |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--keep-last``, ``--keep-secondly``              | number of secondly archives to keep                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--keep-minutely``                               | number of minutely archives to keep                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-H``, ``--keep-hourly``                         | number of hourly archives to keep                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-d``, ``--keep-daily``                          | number of daily archives to keep                                                                |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-w``, ``--keep-weekly``                         | number of weekly archives to keep                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-m``, ``--keep-monthly``                        | number of monthly archives to keep                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-y``, ``--keep-yearly``                         | number of yearly archives to keep                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--save-space``                                  | work slower, but using less space                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                          |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                    |
+    |                                                                                                                                                                                                                                   |
+    | :ref:`common_options`                                                                                                                                                                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB``             | only consider archive names matching the glob. sh: rules apply, see "borg help patterns".       |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -76,6 +78,7 @@ borg prune
         -m, --keep-monthly    number of monthly archives to keep
         -y, --keep-yearly     number of yearly archives to keep
         --save-space          work slower, but using less space
+        -c SECONDS, --checkpoint-interval SECONDS    write checkpoint every SECONDS seconds (Default: 1800)
 
 
     :ref:`common_options`

docs/usage/rcreate.rst

@@ -15,6 +15,7 @@ Examples
     $ borg rcreate --encryption=repokey-blake2-chacha20-poly1305
     # no encryption, not recommended
     $ borg rcreate --encryption=authenticated
+    $ borg rcreate --encryption=authenticated-blake2
     $ borg rcreate --encryption=none
 
     # Remote repository (accesses a remote borg via ssh)

docs/usage/rcreate.rst.inc

@@ -25,6 +25,8 @@ borg rcreate
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--make-parent-dirs``             | create the parent directories of the repository directory, if they are missing.                                                                                                                                                        |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--copy-ae-key``                  | copy the authenticated encryption (AE) key from the key of the other repo (default: new random key).                                                                                                                                   |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                                                                      |
     |                                                                                                                                                                                                                                                                                                                                     |
     | :ref:`common_options`                                                                                                                                                                                                                                                                                                               |
@@ -48,6 +50,7 @@ borg rcreate
         --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-ae-key                  copy the authenticated encryption (AE) key from the key of the other repo (default: new random key).
 
 
     :ref:`common_options`
@@ -83,7 +86,7 @@ Borg will:
    have the key and know the passphrase. Make sure to keep a backup of
    your key **outside** the repository - do not lock yourself out by
    "leaving your keys inside your car" (see :ref:`borg_key_export`).
-   For remote backups the encryption is done locally - the remote machine
+   The encryption is done locally - if you use a remote repository, 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.
@@ -128,27 +131,23 @@ in the upper part of the table, in the lower part is the old and/or unsafe(r) st
 
 .. nanorst: inline-fill
 
-+-----------------------------------+--------------+----------------+--------------------+---------+
-| Mode (K = keyfile or repokey)     | ID-Hash      | Encryption     | Authentication     | V >=    |
-+-----------------------------------+--------------+----------------+--------------------+---------+
-| K-blake2-chacha20-poly1305        | BLAKE2b      | CHACHA20       | POLY1305           | 2.0     |
-+-----------------------------------+--------------+----------------+--------------------+---------+
-| K-chacha20-poly1305               | HMAC-SHA-256 | CHACHA20       | POLY1305           | 2.0     |
-+-----------------------------------+--------------+----------------+--------------------+---------+
-| K-blake2-aes-ocb                  | BLAKE2b      | AES256-OCB     | AES256-OCB         | 2.0     |
-+-----------------------------------+--------------+----------------+--------------------+---------+
-| K-aes-ocb                         | HMAC-SHA-256 | AES256-OCB     | AES256-OCB         | 2.0     |
-+-----------------------------------+--------------+----------------+--------------------+---------+
-| K-blake2                          | BLAKE2b      | AES256-CTR     | BLAKE2b            | 1.1     |
-+-----------------------------------+--------------+----------------+--------------------+---------+
-| K                                 | HMAC-SHA-256 | AES256-CTR     | HMAC-SHA256        | any     |
-+-----------------------------------+--------------+----------------+--------------------+---------+
-| authenticated-blake2              | BLAKE2b      | none           | BLAKE2b            | 1.1     |
-+-----------------------------------+--------------+----------------+--------------------+---------+
-| authenticated                     | HMAC-SHA-256 | none           | HMAC-SHA256        | 1.1     |
-+-----------------------------------+--------------+----------------+--------------------+---------+
-| none                              | SHA-256      | none           | none               | any     |
-+-----------------------------------+--------------+----------------+--------------------+---------+
++-----------------------------------+--------------+----------------+--------------------+
+| Mode (K = keyfile or repokey)     | ID-Hash      | Encryption     | Authentication     |
++-----------------------------------+--------------+----------------+--------------------+
+| K-blake2-chacha20-poly1305        | BLAKE2b      | CHACHA20       | POLY1305           |
++-----------------------------------+--------------+----------------+--------------------+
+| K-chacha20-poly1305               | HMAC-SHA-256 | CHACHA20       | POLY1305           |
++-----------------------------------+--------------+----------------+--------------------+
+| K-blake2-aes-ocb                  | BLAKE2b      | AES256-OCB     | AES256-OCB         |
++-----------------------------------+--------------+----------------+--------------------+
+| K-aes-ocb                         | HMAC-SHA-256 | AES256-OCB     | AES256-OCB         |
++-----------------------------------+--------------+----------------+--------------------+
+| authenticated-blake2              | BLAKE2b      | none           | BLAKE2b            |
++-----------------------------------+--------------+----------------+--------------------+
+| authenticated                     | HMAC-SHA-256 | none           | HMAC-SHA256        |
++-----------------------------------+--------------+----------------+--------------------+
+| none                              | SHA-256      | none           | none               |
++-----------------------------------+--------------+----------------+--------------------+
 
 .. nanorst: inline-replace
 
@@ -158,3 +157,17 @@ case of malicious activity in the repository.
 
 If you do **not** want to encrypt the contents of your backups, but still want to detect
 malicious tampering use an `authenticated` mode. It's like `repokey` minus encryption.
+
+Creating a related repository
++++++++++++++++++++++++++++++
+
+A related repository uses same secret key material as the other/original repository.
+
+By default, only the ID key and chunker secret will be the same (these are important
+for deduplication) and the AE crypto keys will be newly generated random keys.
+
+Optionally, if you use ``--copy-ae-key`` you can also keep the same AE crypto keys
+(used for authenticated encryption). Might be desired e.g. if you want to have less
+keys to manage.
+
+Creating related repositories is useful e.g. if you want to use ``borg transfer`` later.

docs/usage/transfer.rst.inc

@@ -72,9 +72,9 @@ Optionally, it can also upgrade the transferred data.
 
 Suggested use for general purpose archive transfer (not repo upgrades)::
 
-    # initialize DST_REPO reusing key material from SRC_REPO, so that
+    # 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 init --other-repo=SRC_REPO --encryption=DST_ENC
+    borg --repo=DST_REPO rcreate --other-repo=SRC_REPO --encryption=DST_ENC
 
     # transfer archives from SRC_REPO to DST_REPO
     borg --repo=DST_REPO transfer --other-repo=SRC_REPO --dry-run  # check what it would do

setup_docs.py

@@ -315,7 +315,6 @@ class build_man(Command):
         "key_change-location": "key",
         "key_export": "key",
         "key_import": "key",
-        "key_migrate-to-repokey": "key",
         "export-tar": "tar",
         "import-tar": "tar",
         "benchmark_crud": "benchmark",

src/borg/archiver/rcreate.py

@@ -80,7 +80,7 @@ class RCreateMixIn:
            have the key and know the passphrase. Make sure to keep a backup of
            your key **outside** the repository - do not lock yourself out by
            "leaving your keys inside your car" (see :ref:`borg_key_export`).
-           For remote backups the encryption is done locally - the remote machine
+           The encryption is done locally - if you use a remote repository, 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.
@@ -125,27 +125,23 @@ class RCreateMixIn:
 
         .. nanorst: inline-fill
 
-        +-----------------------------------+--------------+----------------+--------------------+---------+
-        | Mode (K = keyfile or repokey)     | ID-Hash      | Encryption     | Authentication     | V >=    |
-        +-----------------------------------+--------------+----------------+--------------------+---------+
-        | K-blake2-chacha20-poly1305        | BLAKE2b      | CHACHA20       | POLY1305           | 2.0     |
-        +-----------------------------------+--------------+----------------+--------------------+---------+
-        | K-chacha20-poly1305               | HMAC-SHA-256 | CHACHA20       | POLY1305           | 2.0     |
-        +-----------------------------------+--------------+----------------+--------------------+---------+
-        | K-blake2-aes-ocb                  | BLAKE2b      | AES256-OCB     | AES256-OCB         | 2.0     |
-        +-----------------------------------+--------------+----------------+--------------------+---------+
-        | K-aes-ocb                         | HMAC-SHA-256 | AES256-OCB     | AES256-OCB         | 2.0     |
-        +-----------------------------------+--------------+----------------+--------------------+---------+
-        | K-blake2                          | BLAKE2b      | AES256-CTR     | BLAKE2b            | 1.1     |
-        +-----------------------------------+--------------+----------------+--------------------+---------+
-        | K                                 | HMAC-SHA-256 | AES256-CTR     | HMAC-SHA256        | any     |
-        +-----------------------------------+--------------+----------------+--------------------+---------+
-        | authenticated-blake2              | BLAKE2b      | none           | BLAKE2b            | 1.1     |
-        +-----------------------------------+--------------+----------------+--------------------+---------+
-        | authenticated                     | HMAC-SHA-256 | none           | HMAC-SHA256        | 1.1     |
-        +-----------------------------------+--------------+----------------+--------------------+---------+
-        | none                              | SHA-256      | none           | none               | any     |
-        +-----------------------------------+--------------+----------------+--------------------+---------+
+        +-----------------------------------+--------------+----------------+--------------------+
+        | Mode (K = keyfile or repokey)     | ID-Hash      | Encryption     | Authentication     |
+        +-----------------------------------+--------------+----------------+--------------------+
+        | K-blake2-chacha20-poly1305        | BLAKE2b      | CHACHA20       | POLY1305           |
+        +-----------------------------------+--------------+----------------+--------------------+
+        | K-chacha20-poly1305               | HMAC-SHA-256 | CHACHA20       | POLY1305           |
+        +-----------------------------------+--------------+----------------+--------------------+
+        | K-blake2-aes-ocb                  | BLAKE2b      | AES256-OCB     | AES256-OCB         |
+        +-----------------------------------+--------------+----------------+--------------------+
+        | K-aes-ocb                         | HMAC-SHA-256 | AES256-OCB     | AES256-OCB         |
+        +-----------------------------------+--------------+----------------+--------------------+
+        | authenticated-blake2              | BLAKE2b      | none           | BLAKE2b            |
+        +-----------------------------------+--------------+----------------+--------------------+
+        | authenticated                     | HMAC-SHA-256 | none           | HMAC-SHA256        |
+        +-----------------------------------+--------------+----------------+--------------------+
+        | none                              | SHA-256      | none           | none               |
+        +-----------------------------------+--------------+----------------+--------------------+
 
         .. nanorst: inline-replace
 
@@ -156,6 +152,19 @@ class RCreateMixIn:
         If you do **not** want to encrypt the contents of your backups, but still want to detect
         malicious tampering use an `authenticated` mode. It's like `repokey` minus encryption.
 
+        Creating a related repository
+        +++++++++++++++++++++++++++++
+
+        A related repository uses same secret key material as the other/original repository.
+
+        By default, only the ID key and chunker secret will be the same (these are important
+        for deduplication) and the AE crypto keys will be newly generated random keys.
+
+        Optionally, if you use ``--copy-ae-key`` you can also keep the same AE crypto keys
+        (used for authenticated encryption). Might be desired e.g. if you want to have less
+        keys to manage.
+
+        Creating related repositories is useful e.g. if you want to use ``borg transfer`` later.
         """
         )
         subparser = subparsers.add_parser(

src/borg/archiver/transfer.py

@@ -117,7 +117,7 @@ class TransferMixIn:
 
         Suggested use for general purpose archive transfer (not repo upgrades)::
 
-            # initialize DST_REPO reusing key material from SRC_REPO, so that
+            # 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 rcreate --other-repo=SRC_REPO --encryption=DST_ENC