build_man

34 files changed, 216 insertions, 125 deletions

diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1
index bf0abc816..041a88a21 100644
--- a/docs/man/borg-benchmark-crud.1
+++ b/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
diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1
index 8f9972d67..92b5515ef 100644
--- a/docs/man/borg-benchmark.1
+++ b/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
diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1
index dd13cbd82..31bc50bba 100644
--- a/docs/man/borg-break-lock.1
+++ b/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
diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1
index aeb5c3db5..29265c0ea 100644
--- a/docs/man/borg-check.1
+++ b/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
diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1
index 9eec2c6b9..9b6f8dfa9 100644
--- a/docs/man/borg-common.1
+++ b/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
diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1
index c9b1b5db7..f159a0875 100644
--- a/docs/man/borg-compact.1
+++ b/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
diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1
index 1a651782f..274aa86ed 100644
--- a/docs/man/borg-compression.1
+++ b/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
diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1
index b6093cfe5..24e0d708c 100644
--- a/docs/man/borg-config.1
+++ b/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
diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1
index e002dacf0..3815b178c 100644
--- a/docs/man/borg-create.1
+++ b/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
diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1
index a3ff02571..8435c20ff 100644
--- a/docs/man/borg-delete.1
+++ b/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,
diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1
index 1a8aebf7b..6cce20acd 100644
--- a/docs/man/borg-diff.1
+++ b/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.
diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1
index 58b2b2028..4a26acb6b 100644
--- a/docs/man/borg-export-tar.1
+++ b/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.
diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1
index d4148eaee..9d155d2e9 100644
--- a/docs/man/borg-extract.1
+++ b/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,
diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1
index 70a9db3d2..9c9f2a11a 100644
--- a/docs/man/borg-import-tar.1
+++ b/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
diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1
index 5112545e1..92f516eb6 100644
--- a/docs/man/borg-info.1
+++ b/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
diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1
index 3c5b83e08..64e68c1f6 100644
--- a/docs/man/borg-init.1
+++ b/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
diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1
index b49c8bddd..9cde3c97f 100644
--- a/docs/man/borg-key-change-passphrase.1
+++ b/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
diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1
index ce63f6142..42e963f0e 100644
--- a/docs/man/borg-key-export.1
+++ b/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
diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1
index f2fc5422d..589d19f54 100644
--- a/docs/man/borg-key-import.1
+++ b/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
diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1
index 57d66eaae..38da5b022 100644
--- a/docs/man/borg-key-migrate-to-repokey.1
+++ b/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
diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1
index 9b0a0221c..4f898d7c7 100644
--- a/docs/man/borg-key.1
+++ b/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
diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1
index 1a4ea9138..ccea21110 100644
--- a/docs/man/borg-list.1
+++ b/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.
diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1
index 6a7d3ad6c..f989d1edc 100644
--- a/docs/man/borg-mount.1
+++ b/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
diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1
index 3115154e1..9488d77b0 100644
--- a/docs/man/borg-patterns.1
+++ b/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