Merge pull request #6313 from borgbackup/rel120

release 1.2.0

docs/changes.rst

@@ -217,8 +217,9 @@ The best check that everything is ok is to run a dry-run extraction::
 Change Log
 ==========
 
-Version 1.2.0 (not released yet)
---------------------------------
+
+Version 1.2.0 (2022-02-22 22:02:22 :-)
+--------------------------------------
 
 Please note:
 
@@ -303,6 +304,11 @@ Fixes:
 
   - derive really freed space from quota use before/after, #5679
   - do not say "freeable", but "maybe freeable" (based on hint, unsure)
+- fix race conditions in internal SaveFile function, #6306 #6028
+- implement internal safe_unlink (was: truncate_and_unlink) function more safely:
+  usually it does not truncate any more, only under "disk full" circumstances
+  and only if there is only one hardlink.
+  see: https://github.com/borgbackup/borg/discussions/6286
 
 Other changes:
 
@@ -320,6 +326,8 @@ Other changes:
   - init: explain the encryption modes better
   - clarify usage of patternfile roots
   - put import-tar docs into same file as export-tar docs
+  - explain the difference between a path that ends with or without a slash,
+    #6297
 
 
 Version 1.2.0rc1 (2022-02-05)

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-02-05" "" "borg backup tool"
+.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

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-02-05" "" "borg backup tool"
+.TH "BORG-BENCHMARK" 1 "2022-02-19" "" "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-02-05" "" "borg backup tool"
+.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

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-02-05" "" "borg backup tool"
+.TH "BORG-CHECK" 1 "2022-02-19" "" "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-02-05" "" "borg backup tool"
+.TH "BORG-COMMON" 1 "2022-02-19" "" "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-02-05" "" "borg backup tool"
+.TH "BORG-COMPACT" 1 "2022-02-19" "" "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-02-05" "" "borg backup tool"
+.TH "BORG-COMPRESSION" 1 "2022-02-19" "" "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-02-05" "" "borg backup tool"
+.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

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-02-05" "" "borg backup tool"
+.TH "BORG-CREATE" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .SH SYNOPSIS
@@ -117,9 +117,9 @@ how much your repository will grow. Please note that the "All archives" stats re
 the state after creation. Also, the \fB\-\-stats\fP and \fB\-\-dry\-run\fP options are mutually
 exclusive because the data is not actually compressed and deduplicated during a dry run.
 .sp
-See the output of the "borg help patterns" command for more help on exclude patterns.
+For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
 .sp
-See the output of the "borg help placeholders" command for more help on placeholders.
+For more help on placeholders, see the \fIborg_placeholders\fP command output.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -362,8 +362,7 @@ $ find ~ \-size \-1000k \-print0 | borg create \e
 .sp
 The \fB\-\-exclude\fP patterns are not like tar. In tar \fB\-\-exclude\fP .bundler/gems will
 exclude foo/.bundler/gems. In borg it will not, you need to use \fB\-\-exclude\fP
-\(aq*/.bundler/gems\(aq to get the same effect. See \fBborg help patterns\fP for
-more information.
+\(aq*/.bundler/gems\(aq to get the same effect.
 .sp
 In addition to using \fB\-\-exclude\fP patterns, it is possible to use
 \fB\-\-exclude\-if\-present\fP to specify the name of a filesystem object (e.g. a file

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-02-05" "" "borg backup tool"
+.TH "BORG-DELETE" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .SH SYNOPSIS
@@ -55,7 +55,7 @@ Please note that the "All archives" stats refer to the state after deletion.
 You can delete multiple archives by specifying their common prefix, if they
 have one, using the \fB\-\-prefix PREFIX\fP option. You can also specify a shell
 pattern to match multiple archives using the \fB\-\-glob\-archives GLOB\fP option
-(for more info on these patterns, see \fBborg help patterns\fP). Note that these
+(for more info on these patterns, see \fIborg_patterns\fP). Note that these
 two options are mutually exclusive.
 .sp
 To avoid accidentally deleting archives, especially when using glob patterns,

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-02-05" "" "borg backup tool"
+.TH "BORG-DIFF" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .SH SYNOPSIS
@@ -50,7 +50,7 @@ If you did not create the archives with different chunker params,
 pass \fB\-\-same\-chunker\-params\fP\&.
 Note that the chunker params changed from Borg 0.xx to 1.0.
 .sp
-See the output of the "borg help patterns" command for more help on exclude patterns.
+For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

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-02-05" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS
@@ -72,7 +72,7 @@ By default the entire archive is extracted but a subset of files and directories
 can be selected by passing a list of \fBPATHs\fP as arguments.
 The file selection can further be restricted by using the \fB\-\-exclude\fP option.
 .sp
-See the output of the "borg help patterns" command for more help on exclude patterns.
+For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
 .sp
 \fB\-\-progress\fP can be slower than no progress display, since it makes one additional
 pass over the archive metadata.

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-02-05" "" "borg backup tool"
+.TH "BORG-EXTRACT" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .SH SYNOPSIS
@@ -40,7 +40,7 @@ archive is extracted but a subset of files and directories can be selected
 by passing a list of \fBPATHs\fP as arguments. The file selection can further
 be restricted by using the \fB\-\-exclude\fP option.
 .sp
-See the output of the "borg help patterns" command for more help on exclude patterns.
+For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
 .sp
 By using \fB\-\-dry\-run\fP, you can do all extraction steps except actually writing the
 output data: reading metadata and data chunks from the repo, checking the hash/hmac,

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-02-05" "" "borg backup tool"
+.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

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-02-05" "" "borg backup tool"
+.TH "BORG-INFO" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS

docs/man/borg-init.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-INIT" 1 "2022-02-05" "" "borg backup tool"
+.TH "BORG-INIT" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .SH SYNOPSIS
@@ -37,32 +37,61 @@ borg [common options] init [options] [REPOSITORY]
 .sp
 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
-Encryption can be enabled at repository init time. It cannot be changed later.
+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
-It is not recommended to work without encryption. Repository encryption protects
-you e.g. against the case that an attacker has access to your backup repository.
-.sp
-Borg relies on randomly generated key material and uses that for chunking, id
-generation, encryption and authentication. The key material is encrypted using
-the passphrase you give before it is stored on\-disk.
+Use \fBrepokey\fP:
+.INDENT 0.0
+.INDENT 3.5
 .sp
-You need to be careful with the key / the passphrase:
+.nf
+.ft C
+borg init \-\-encryption repokey /path/to/repo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .sp
-If you want "passphrase\-only" security, use one of the repokey modes. The
-key will be stored inside the repository (in its "config" file). In above
-mentioned attack scenario, the attacker will have the key (but not the
-passphrase).
+Or \fBrepokey\-blake2\fP depending on which is faster on your client machines (see below):
+.INDENT 0.0
+.INDENT 3.5
 .sp
-If you want "passphrase and having\-the\-key" security, use one of the keyfile
-modes. The key will be stored in your home directory (in .config/borg/keys).
-In the attack scenario, the attacker who has just access to your repo won\(aqt
-have the key (and also not the passphrase).
+.nf
+.ft C
+borg init \-\-encryption repokey\-blake2 /path/to/repo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .sp
-Make a backup copy of the key file (keyfile mode) or repo config file
-(repokey mode) and keep it at a safe place, so you still have the key in
-case it gets corrupted or lost. Also keep the passphrase at a safe place.
-The backup that is encrypted with that key won\(aqt help you with that, of course.
+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).
+.IP 3. 3
+Encrypt the key with your passphrase.
+.IP 4. 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
+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
+"leaving your keys inside your car" (see \fIborg_key_export\fP).
+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
+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
+.SS Picking a passphrase
 .sp
 Make sure you use a good passphrase. Not too short, not too simple. The real
 encryption / decryption key is encrypted with / locked by your passphrase.
@@ -84,13 +113,21 @@ 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 Encryption modes
+.SS More encryption modes
+.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.
+.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).
 .sp
-You can choose from the encryption modes seen in the table below on a per\-repo
-basis. The mode determines encryption algorithm, hash/MAC algorithm and also the
-key storage location.
+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\&.
 .sp
-Example: \fIborg init \-\-encryption repokey ...\fP
+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.
 .\" nanorst: inline-fill
 .
 .TS

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-02-05" "" "borg backup tool"
+.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

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-02-05" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" 1 "2022-02-19" "" "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-02-05" "" "borg backup tool"
+.TH "BORG-KEY-IMPORT" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .SH SYNOPSIS

docs/man/borg-key-migrate-to-repokey.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-MIGRATE-TO-REPOKEY" 1 "2022-02-05" "" "borg backup tool"
+.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .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-02-05" "" "borg backup tool"
+.TH "BORG-KEY" 1 "2022-02-19" "" "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-02-05" "" "borg backup tool"
+.TH "BORG-LIST" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .SH SYNOPSIS
@@ -37,7 +37,7 @@ borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
 .sp
 This command lists the contents of a repository or an archive.
 .sp
-See the "borg help patterns" command for more help on exclude patterns.
+For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

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-02-05" "" "borg backup tool"
+.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

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-02-05" "" "borg backup tool"
+.TH "BORG-PATTERNS" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
@@ -46,19 +46,15 @@ store all files as \fIsome/path/.../file.ext\fP and \fBborg create
 /path/to/repo /home/user\fP will store all files as
 \fIhome/user/.../file.ext\fP\&.
 .sp
+A directory exclusion pattern can end either with or without a slash (\(aq/\(aq).
+If it ends with a slash, such as \fIsome/path/\fP, the directory will be
+included but not its content. If it does not end with a slash, such as
+\fIsome/path\fP, both the directory and content will be excluded.
+.sp
 File patterns support these styles: fnmatch, shell, regular expressions,
 path prefixes and path full\-matches. By default, fnmatch is used for
 \fB\-\-exclude\fP patterns and shell\-style is used for the \fB\-\-pattern\fP
-.IP "System Message: ERROR/3 (docs/borg-patterns.rst:, line 43)"
-Unexpected indentation.
-.INDENT 0.0
-.INDENT 3.5
 option. For commands that support patterns in their \fBPATH\fP argument
-.UNINDENT
-.UNINDENT
-.IP "System Message: WARNING/2 (docs/borg-patterns.rst:, line 44)"
-Block quote ends without a blank line; unexpected unindent.
-.sp
 like (\fBborg list\fP), the default pattern is path prefix.
 .sp
 Starting with Borg 1.2, for all but regular expression pattern matching
@@ -187,69 +183,128 @@ sh:/home/*/.thumbnails
 some file with spaces.txt
 EOF
 $ borg create \-\-exclude\-from exclude.txt backup /
-
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
 A more general and easier to use way to define filename matching patterns exists
-with the \(ga\(ga\-\-pattern\(ga\(ga and \(ga\(ga\-\-patterns\-from\(ga\(ga options. Using these, you may
+with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you may
 specify the backup roots (starting points) and patterns for inclusion/exclusion.
-A root path starts with the prefix \(gaR\(ga, followed by a path (a plain path, not a
+A root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a
 file pattern). An include rule starts with the prefix +, an exclude rule starts
 with the prefix \-, an exclude\-norecurse rule starts with !, all followed by a pattern.
-
-\&.. note::
-
-    Via \(ga\(ga\-\-pattern\(ga\(ga or \(ga\(ga\-\-patterns\-from\(ga\(ga you can define BOTH inclusion and exclusion
-    of files using pattern prefixes \(ga\(ga+\(ga\(ga and \(ga\(ga\-\(ga\(ga. With \(ga\(ga\-\-exclude\(ga\(ga and
-    \(ga\(ga\-\-exclude\-from\(ga\(ga ONLY excludes are defined.
-
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Via \fB\-\-pattern\fP or \fB\-\-patterns\-from\fP you can define BOTH inclusion and exclusion
+of files using pattern prefixes \fB+\fP and \fB\-\fP\&. With \fB\-\-exclude\fP and
+\fB\-\-exclude\-from\fP ONLY excludes are defined.
+.UNINDENT
+.UNINDENT
+.sp
 Inclusion patterns are useful to include paths that are contained in an excluded
 path. The first matching pattern is used so if an include pattern matches before
 an exclude pattern, the file is backed up. If an exclude\-norecurse pattern matches
 a directory, it won\(aqt recurse into it and won\(aqt discover any potential matches for
 include rules below that directory.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+It\(aqs possible that a sub\-directory/file is matched while parent directories are not.
+In that case, parent directories are not backed up thus their user, group, permission,
+etc. can not be restored.
+.UNINDENT
+.UNINDENT
+.sp
+Note that the default pattern style for \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP is
+shell style (\fIsh:\fP), so those patterns behave similar to rsync include/exclude
+patterns. The pattern style can be set via the \fIP\fP prefix.
+.sp
+Patterns (\fB\-\-pattern\fP) and excludes (\fB\-\-exclude\fP) from the command line are
+considered first (in the order of appearance). Then patterns from \fB\-\-patterns\-from\fP
+are added. Exclusion patterns from \fB\-\-exclude\-from\fP files are appended last.
+.sp
+Examples:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# backup pics, but not the ones from 2018, except the good ones:
+# note: using = is essential to avoid cmdline argument parsing issues.
+borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics
 
-\&.. note::
-
-    It\(aqs possible that a sub\-directory/file is matched while parent directories are not.
-    In that case, parent directories are not backed up thus their user, group, permission,
-    etc. can not be restored.
-
-Note that the default pattern style for \(ga\(ga\-\-pattern\(ga\(ga and \(ga\(ga\-\-patterns\-from\(ga\(ga is
-shell style (\(gash:\(ga), so those patterns behave similar to rsync include/exclude
-patterns. The pattern style can be set via the \(gaP\(ga prefix.
-
-Patterns (\(ga\(ga\-\-pattern\(ga\(ga) and excludes (\(ga\(ga\-\-exclude\(ga\(ga) from the command line are
-considered first (in the order of appearance). Then patterns from \(ga\(ga\-\-patterns\-from\(ga\(ga
-are added. Exclusion patterns from \(ga\(ga\-\-exclude\-from\(ga\(ga files are appended last.
-
-Examples::
-
-    # backup pics, but not the ones from 2018, except the good ones:
-    # note: using = is essential to avoid cmdline argument parsing issues.
-    borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics
-
-    # use a file with patterns:
-    borg create \-\-patterns\-from patterns.lst repo::arch
-
-The patterns.lst file could look like that::
+# use a file with patterns:
+borg create \-\-patterns\-from patterns.lst repo::arch
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The patterns.lst file could look like that:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# "sh:" pattern style is the default, so the following line is not needed:
+P sh
+R /
+# can be rebuild
+\- /home/*/.cache
+# they\(aqre downloads for a reason
+\- /home/*/Downloads
+# susan is a nice person
+# include susans home
++ /home/susan
+# also back up this exact file
++ pf:/home/bobby/specialfile.txt
+# don\(aqt backup the other home directories
+\- /home/*
+# don\(aqt even look in /proc
+! /proc
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+You can specify recursion roots either on the command line or in a patternfile:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# these two commands do the same thing
+borg create \-\-exclude /home/bobby/junk repo::arch /home/bobby /home/susan
+borg create \-\-patterns\-from patternfile.lst repo::arch
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The patternfile:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# note that excludes use fm: by default and patternfiles use sh: by default.
+# therefore, we need to specify fm: to have the same exact behavior.
+P fm
+R /home/bobby
+R /home/susan
 
-    # "sh:" pattern style is the default, so the following line is not needed:
-    P sh
-    R /
-    # can be rebuild
-    \- /home/*/.cache
-    # they\(aqre downloads for a reason
-    \- /home/*/Downloads
-    # susan is a nice person
-    # include susans home
-    + /home/susan
-    # don\(aqt backup the other home directories
-    \- /home/*
-    # don\(aqt even look in /proc
-    ! /proc
+\- /home/bobby/junk
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
+.sp
+This allows you to share the same patterns between multiple repositories
+without needing to specify them on the command line.
 .SH AUTHOR
 The Borg Collective
 .\" Generated by docutils manpage writer.

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-02-05" "" "borg backup tool"
+.TH "BORG-PLACEHOLDERS" 1 "2022-02-19" "" "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-02-05" "" "borg backup tool"
+.TH "BORG-PRUNE" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .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-02-05" "" "borg backup tool"
+.TH "BORG-RECREATE" 1 "2022-02-19" "" "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-02-05" "" "borg backup tool"
+.TH "BORG-RENAME" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .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-02-05" "" "borg backup tool"
+.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

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

docs/man/borg-upgrade.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-UPGRADE" 1 "2022-02-05" "" "borg backup tool"
+.TH "BORG-UPGRADE" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .SH SYNOPSIS

docs/man/borg-with-lock.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-WITH-LOCK" 1 "2022-02-05" "" "borg backup tool"
+.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

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-02-05" "" "borg backup tool"
+.TH "BORG" 1 "2022-02-19" "" "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-02-05" "" "borg backup tool"
+.TH "BORGFS" 1 "2022-02-19" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS

docs/quickstart_example.rst.inc

@@ -50,10 +50,14 @@
 
     $ borg extract /path/to/repo::Monday
 
-7. Recover disk space by manually deleting the *Monday* archive::
+7. Delete the *Monday* archive (please note that this does **not** free repo disk space)::
 
     $ borg delete /path/to/repo::Monday
 
+8. Recover disk space by compacting the segment files in the repo::
+
+    $ borg compact /path/to/repo
+
 .. Note::
     Borg is quiet by default (it works on WARNING log level).
     You can use options like ``--progress`` or ``--list`` to get specific

docs/usage/create.rst.inc

@@ -260,16 +260,15 @@ how much your repository will grow. Please note that the "All archives" stats re
 the state after creation. Also, the ``--stats`` and ``--dry-run`` options are mutually
 exclusive because the data is not actually compressed and deduplicated during a dry run.
 
-See the output of the "borg help patterns" command for more help on exclude patterns.
+For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
 
-See the output of the "borg help placeholders" command for more help on placeholders.
+For more help on placeholders, see the :ref:`borg_placeholders` command output.
 
 .. man NOTES
 
 The ``--exclude`` patterns are not like tar. In tar ``--exclude`` .bundler/gems will
 exclude foo/.bundler/gems. In borg it will not, you need to use ``--exclude``
-'\*/.bundler/gems' to get the same effect. See ``borg help patterns`` for
-more information.
+'\*/.bundler/gems' to get the same effect.
 
 In addition to using ``--exclude`` patterns, it is possible to use
 ``--exclude-if-present`` to specify the name of a filesystem object (e.g. a file

docs/usage/delete.rst.inc

@@ -112,7 +112,7 @@ Please note that the "All archives" stats refer to the state after deletion.
 You can delete multiple archives by specifying their common prefix, if they
 have one, using the ``--prefix PREFIX`` option. You can also specify a shell
 pattern to match multiple archives using the ``--glob-archives GLOB`` option
-(for more info on these patterns, see ``borg help patterns``). Note that these
+(for more info on these patterns, see :ref:`borg_patterns`). Note that these
 two options are mutually exclusive.
 
 To avoid accidentally deleting archives, especially when using glob patterns,

docs/usage/diff.rst.inc

@@ -102,4 +102,4 @@ If you did not create the archives with different chunker params,
 pass ``--same-chunker-params``.
 Note that the chunker params changed from Borg 0.xx to 1.0.
 
-See the output of the "borg help patterns" command for more help on exclude patterns.
+For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.

docs/usage/export-tar.rst.inc

@@ -112,7 +112,7 @@ By default the entire archive is extracted but a subset of files and directories
 can be selected by passing a list of ``PATHs`` as arguments.
 The file selection can further be restricted by using the ``--exclude`` option.
 
-See the output of the "borg help patterns" command for more help on exclude patterns.
+For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
 
 ``--progress`` can be slower than no progress display, since it makes one additional
 pass over the archive metadata.

docs/usage/extract.rst.inc

@@ -106,7 +106,7 @@ archive is extracted but a subset of files and directories can be selected
 by passing a list of ``PATHs`` as arguments. The file selection can further
 be restricted by using the ``--exclude`` option.
 
-See the output of the "borg help patterns" command for more help on exclude patterns.
+For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
 
 By using ``--dry-run``, you can do all extraction steps except actually writing the
 output data: reading metadata and data chunks from the repo, checking the hash/hmac,

docs/usage/help.rst.inc

@@ -20,10 +20,15 @@ store all files as `some/path/.../file.ext` and ``borg create
 /path/to/repo /home/user`` will store all files as
 `home/user/.../file.ext`.
 
+A directory exclusion pattern can end either with or without a slash ('/').
+If it ends with a slash, such as `some/path/`, the directory will be
+included but not its content. If it does not end with a slash, such as
+`some/path`, both the directory and content will be excluded.
+
 File patterns support these styles: fnmatch, shell, regular expressions,
 path prefixes and path full-matches. By default, fnmatch is used for
 ``--exclude`` patterns and shell-style is used for the ``--pattern``
- option. For commands that support patterns in their ``PATH`` argument
+option. For commands that support patterns in their ``PATH`` argument
 like (``borg list``), the default pattern is path prefix.
 
 Starting with Borg 1.2, for all but regular expression pattern matching
@@ -144,64 +149,85 @@ Examples::
     EOF
     $ borg create --exclude-from exclude.txt backup /
 
-    A more general and easier to use way to define filename matching patterns exists
-    with the ``--pattern`` and ``--patterns-from`` options. Using these, you may
-    specify the backup roots (starting points) and patterns for inclusion/exclusion.
-    A root path starts with the prefix `R`, followed by a path (a plain path, not a
-    file pattern). An include rule starts with the prefix +, an exclude rule starts
-    with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
-
-    .. note::
-
-        Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion
-        of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
-        ``--exclude-from`` ONLY excludes are defined.
-
-    Inclusion patterns are useful to include paths that are contained in an excluded
-    path. The first matching pattern is used so if an include pattern matches before
-    an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches
-    a directory, it won't recurse into it and won't discover any potential matches for
-    include rules below that directory.
-
-    .. note::
-
-        It's possible that a sub-directory/file is matched while parent directories are not.
-        In that case, parent directories are not backed up thus their user, group, permission,
-        etc. can not be restored.
-
-    Note that the default pattern style for ``--pattern`` and ``--patterns-from`` is
-    shell style (`sh:`), so those patterns behave similar to rsync include/exclude
-    patterns. The pattern style can be set via the `P` prefix.
-
-    Patterns (``--pattern``) and excludes (``--exclude``) from the command line are
-    considered first (in the order of appearance). Then patterns from ``--patterns-from``
-    are added. Exclusion patterns from ``--exclude-from`` files are appended last.
-
-    Examples::
-
-        # backup pics, but not the ones from 2018, except the good ones:
-        # note: using = is essential to avoid cmdline argument parsing issues.
-        borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
-
-        # use a file with patterns:
-        borg create --patterns-from patterns.lst repo::arch
-
-    The patterns.lst file could look like that::
-
-        # "sh:" pattern style is the default, so the following line is not needed:
-        P sh
-        R /
-        # can be rebuild
-        - /home/*/.cache
-        # they're downloads for a reason
-        - /home/*/Downloads
-        # susan is a nice person
-        # include susans home
-        + /home/susan
-        # don't backup the other home directories
-        - /home/*
-        # don't even look in /proc
-        ! /proc
+A more general and easier to use way to define filename matching patterns exists
+with the ``--pattern`` and ``--patterns-from`` options. Using these, you may
+specify the backup roots (starting points) and patterns for inclusion/exclusion.
+A root path starts with the prefix `R`, followed by a path (a plain path, not a
+file pattern). An include rule starts with the prefix +, an exclude rule starts
+with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
+
+.. note::
+
+    Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion
+    of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
+    ``--exclude-from`` ONLY excludes are defined.
+
+Inclusion patterns are useful to include paths that are contained in an excluded
+path. The first matching pattern is used so if an include pattern matches before
+an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches
+a directory, it won't recurse into it and won't discover any potential matches for
+include rules below that directory.
+
+.. note::
+
+    It's possible that a sub-directory/file is matched while parent directories are not.
+    In that case, parent directories are not backed up thus their user, group, permission,
+    etc. can not be restored.
+
+Note that the default pattern style for ``--pattern`` and ``--patterns-from`` is
+shell style (`sh:`), so those patterns behave similar to rsync include/exclude
+patterns. The pattern style can be set via the `P` prefix.
+
+Patterns (``--pattern``) and excludes (``--exclude``) from the command line are
+considered first (in the order of appearance). Then patterns from ``--patterns-from``
+are added. Exclusion patterns from ``--exclude-from`` files are appended last.
+
+Examples::
+
+    # backup pics, but not the ones from 2018, except the good ones:
+    # note: using = is essential to avoid cmdline argument parsing issues.
+    borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
+
+    # use a file with patterns:
+    borg create --patterns-from patterns.lst repo::arch
+
+The patterns.lst file could look like that::
+
+    # "sh:" pattern style is the default, so the following line is not needed:
+    P sh
+    R /
+    # can be rebuild
+    - /home/*/.cache
+    # they're downloads for a reason
+    - /home/*/Downloads
+    # susan is a nice person
+    # include susans home
+    + /home/susan
+    # also back up this exact file
+    + pf:/home/bobby/specialfile.txt
+    # don't backup the other home directories
+    - /home/*
+    # don't even look in /proc
+    ! /proc
+
+You can specify recursion roots either on the command line or in a patternfile::
+
+    # these two commands do the same thing
+    borg create --exclude /home/bobby/junk repo::arch /home/bobby /home/susan
+    borg create --patterns-from patternfile.lst repo::arch
+
+The patternfile::
+
+    # note that excludes use fm: by default and patternfiles use sh: by default.
+    # therefore, we need to specify fm: to have the same exact behavior.
+    P fm
+    R /home/bobby
+    R /home/susan
+
+    - /home/bobby/junk
+
+This allows you to share the same patterns between multiple repositories
+without needing to specify them on the command line.
 
 .. _borg_placeholders:
 
@@ -223,11 +249,11 @@ and ``--remote-path`` values support these placeholders:
 
 {now}
     The current local date and time, by default in ISO-8601 format.
-    You can also supply your own `format string <https://docs.python.org/3.5/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {now:%Y-%m-%d_%H:%M:%S}
+    You can also supply your own `format string <https://docs.python.org/3.8/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {now:%Y-%m-%d_%H:%M:%S}
 
 {utcnow}
     The current UTC date and time, by default in ISO-8601 format.
-    You can also supply your own `format string <https://docs.python.org/3.5/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {utcnow:%Y-%m-%d_%H:%M:%S}
+    You can also supply your own `format string <https://docs.python.org/3.8/library/datetime.html#strftime-and-strptime-behavior>`_, e.g. {utcnow:%Y-%m-%d_%H:%M:%S}
 
 {user}
     The user name (or UID, if no name is available) of the user running borg.

docs/usage/init.rst.inc

@@ -62,31 +62,41 @@ Description
 This command initializes an empty repository. A repository is a filesystem
 directory containing the deduplicated data from zero or more archives.
 
-Encryption can be enabled at repository init time. It cannot be changed later.
+Encryption mode TLDR
+++++++++++++++++++++
 
-It is not recommended to work without encryption. Repository encryption protects
-you e.g. against the case that an attacker has access to your backup repository.
+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.
 
-Borg relies on randomly generated key material and uses that for chunking, id
-generation, encryption and authentication. The key material is encrypted using
-the passphrase you give before it is stored on-disk.
+Use ``repokey``::
 
-You need to be careful with the key / the passphrase:
+    borg init --encryption repokey /path/to/repo
 
-If you want "passphrase-only" security, use one of the repokey modes. The
-key will be stored inside the repository (in its "config" file). In above
-mentioned attack scenario, the attacker will have the key (but not the
-passphrase).
+Or ``repokey-blake2`` depending on which is faster on your client machines (see below)::
 
-If you want "passphrase and having-the-key" security, use one of the keyfile
-modes. The key will be stored in your home directory (in .config/borg/keys).
-In the attack scenario, the attacker who has just access to your repo won't
-have the key (and also not the passphrase).
+    borg init --encryption repokey-blake2 /path/to/repo
 
-Make a backup copy of the key file (keyfile mode) or repo config file
-(repokey mode) and keep it at a safe place, so you still have the key in
-case it gets corrupted or lost. Also keep the passphrase at a safe place.
-The backup that is encrypted with that key won't help you with that, of course.
+Borg will:
+
+1. Ask you to come up with a passphrase.
+2. Create a borg key (which contains 3 random secrets. See :ref:`key_files`).
+3. Encrypt the key with your passphrase.
+4. Store the encrypted borg key inside the repository directory (in the repo config).
+   This is why it is essential to use a secure passphrase.
+5. 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 **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
+   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.
+6. 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.
+
+Picking a passphrase
+++++++++++++++++++++
 
 Make sure you use a good passphrase. Not too short, not too simple. The real
 encryption / decryption key is encrypted with / locked by your passphrase.
@@ -106,14 +116,22 @@ a different keyboard layout.
 You can change your passphrase for existing repos at any time, it won't affect
 the encryption/decryption key or other secrets.
 
-Encryption modes
-++++++++++++++++
+More encryption modes
++++++++++++++++++++++
+
+Only use ``--encryption none`` 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.
+
+If you want "passphrase and having-the-key" security, use ``--encryption keyfile``.
+The key will be stored in your home directory (in ``~/.config/borg/keys``).
 
-You can choose from the encryption modes seen in the table below on a per-repo
-basis. The mode determines encryption algorithm, hash/MAC algorithm and also the
-key storage location.
+If you do **not** want to encrypt the contents of your backups, but still
+want to detect malicious tampering use ``--encryption authenticated``.
 
-Example: `borg init --encryption repokey ...`
+If ``BLAKE2b`` is faster than ``SHA-256`` on your hardware, use ``--encryption authenticated-blake2``,
+``--encryption repokey-blake2`` or ``--encryption keyfile-blake2``. Note: for remote backups
+the hashing is done on your local machine.
 
 .. nanorst: inline-fill
 

docs/usage/list.rst.inc

@@ -105,7 +105,7 @@ Description
 
 This command lists the contents of a repository or an archive.
 
-See the "borg help patterns" command for more help on exclude patterns.
+For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
 
 .. man NOTES