Merge pull request #2701 from enkore/docs/fixes

docs: assorted formatting fixes

docs/man/borg-benchmark-crud.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CRUD 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-BENCHMARK-CRUD 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .

docs/man/borg-benchmark.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .

docs/man/borg-break-lock.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BREAK-LOCK 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .

docs/man/borg-change-passphrase.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHANGE-PASSPHRASE 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-CHANGE-PASSPHRASE 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-change-passphrase \- Change repository key file passphrase
 .

docs/man/borg-check.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHECK 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-CHECK 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .
@@ -55,7 +55,7 @@ stored in the segments.
 If you use a remote repo server via ssh:, the repo check is executed on the
 repo server without causing significant network traffic.
 .IP \(bu 2
-The repository check can be skipped using the \-\-archives\-only option.
+The repository check can be skipped using the \fB\-\-archives\-only\fP option.
 .UNINDENT
 .sp
 Second, the consistency and correctness of the archive metadata is verified:
@@ -84,10 +84,10 @@ decryption and this is always done client\-side, because key access will be
 required).
 .IP \(bu 2
 The archive checks can be time consuming, they can be skipped using the
-\-\-repository\-only option.
+\fB\-\-repository\-only\fP option.
 .UNINDENT
 .sp
-The \-\-verify\-data option will perform a full integrity verification (as opposed to
+The \fB\-\-verify\-data\fP option will perform a full integrity verification (as opposed to
 checking the CRC32 of the segment) of data, which means reading the data from the
 repository, decrypting and decompressing it. This is a cryptographic verification,
 which will detect (accidental) corruption. For encrypted repositories it is
@@ -113,7 +113,7 @@ only perform repository checks
 only perform archives checks
 .TP
 .B \-\-verify\-data
-perform cryptographic archive data integrity verification (conflicts with \-\-repository\-only)
+perform cryptographic archive data integrity verification (conflicts with \fB\-\-repository\-only\fP)
 .TP
 .B \-\-repair
 attempt to repair any inconsistencies found
@@ -125,7 +125,10 @@ work slower, but using less space
 .INDENT 0.0
 .TP
 .B \-P\fP,\fB  \-\-prefix
-only consider archive names starting with this prefix
+only consider archive names starting with this prefix.
+.TP
+.B \-a\fP,\fB  \-\-glob\-archives
+only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
 .TP
 .B \-\-sort\-by
 Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp

docs/man/borg-common.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMMON 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-COMMON 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .

docs/man/borg-compression.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPRESSION 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .
@@ -32,57 +32,48 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH DESCRIPTION
 .sp
+It is no problem to mix different compression methods in one repo,
+deduplication is done on the source data chunks (not on the compressed
+or encrypted data).
+.sp
+If some specific chunk was once compressed and stored into the repo, creating
+another backup that also uses this chunk will not change the stored chunk.
+So if you use different compression specs for the backups, whichever stores a
+chunk first determines its compression. See also borg recreate.
+.sp
 Compression is lz4 by default. If you want something else, you have to specify what you want.
 .sp
 Valid compression specifiers are:
-.sp
-none
 .INDENT 0.0
-.INDENT 3.5
+.TP
+.B none
 Do not compress.
-.UNINDENT
-.UNINDENT
-.sp
-lz4
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B lz4
 Use lz4 compression. High speed, low compression. (default)
-.UNINDENT
-.UNINDENT
-.sp
-zlib[,L]
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B zlib[,L]
 Use zlib ("gz") compression. Medium speed, medium compression.
 If you do not explicitely give the compression level L (ranging from 0
 to 9), it will use level 6.
 Giving level 0 (means "no compression", but still has zlib protocol
 overhead) is usually pointless, you better use "none" compression.
-.UNINDENT
-.UNINDENT
-.sp
-lzma[,L]
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B lzma[,L]
 Use lzma ("xz") compression. Low speed, high compression.
 If you do not explicitely give the compression level L (ranging from 0
 to 9), it will use level 6.
 Giving levels above 6 is pointless and counterproductive because it does
 not compress better due to the buffer size used by borg \- but it wastes
 lots of CPU cycles and RAM.
-.UNINDENT
-.UNINDENT
-.sp
-auto,C[,L]
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B auto,C[,L]
 Use a built\-in heuristic to decide per chunk whether to compress or not.
 The heuristic tries with lz4 whether the data is compressible.
 For incompressible data, it will not use compression (uses "none").
 For compressible data, it uses the given C[,L] compression \- with C[,L]
 being any valid compression specifier.
 .UNINDENT
-.UNINDENT
 .sp
 Examples:
 .INDENT 0.0
@@ -99,17 +90,6 @@ borg create \-\-compression auto,lzma ...
 .fi
 .UNINDENT
 .UNINDENT
-.sp
-General remarks:
-.sp
-It is no problem to mix different compression methods in one repo,
-deduplication is done on the source data chunks (not on the compressed
-or encrypted data).
-.sp
-If some specific chunk was once compressed and stored into the repo, creating
-another backup that also uses this chunk will not change the stored chunk.
-So if you use different compression specs for the backups, whichever stores a
-chunk first determines its compression. See also borg recreate.
 .SH AUTHOR
 The Borg Collective
 .\" Generated by docutils manpage writer.

docs/man/borg-create.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CREATE 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-CREATE 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .
@@ -54,7 +54,7 @@ In the archive name, you may use the following placeholders:
 {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
 .sp
 To speed up pulling backups over sshfs and similar network file systems which do
-not provide correct inode information the \-\-ignore\-inode flag can be used. This
+not provide correct inode information the \fB\-\-ignore\-inode\fP flag can be used. This
 potentially decreases reliability of change detection, while avoiding always reading
 all files on these file systems.
 .sp
@@ -63,7 +63,7 @@ creation of a new archive to ensure fast operation. This is because the file cac
 is used to determine changed files quickly uses absolute filenames.
 If this is not possible, consider creating a bind mount to a stable location.
 .sp
-The \-\-progress option shows (from left to right) Original, Compressed and Deduplicated
+The \fB\-\-progress\fP option shows (from left to right) Original, Compressed and Deduplicated
 (O, C and D, respectively), then the Number of files (N) processed so far, followed by
 the currently processed path.
 .sp
@@ -98,6 +98,9 @@ only display items with the given status characters
 .TP
 .B \-\-json
 output stats as JSON (implies \-\-stats)
+.TP
+.B \-\-no\-cache\-sync
+experimental: do not synchronize the cache. Implies \-\-no\-files\-cache.
 .UNINDENT
 .SS Exclusion options
 .INDENT 0.0
@@ -118,10 +121,10 @@ exclude directories that are tagged by containing a filesystem object with the g
 if tag objects are specified with \-\-exclude\-if\-present, don\(aqt omit the tag objects themselves from the backup archive
 .TP
 .BI \-\-pattern \ PATTERN
-include/exclude paths matching PATTERN
+experimental: include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-read include/exclude patterns from PATTERNFILE, one per line
+experimental: read include/exclude patterns from PATTERNFILE, one per line
 .UNINDENT
 .SS Filesystem options
 .INDENT 0.0
@@ -181,11 +184,7 @@ $ borg create /path/to/repo::my\-files \e
     \-\-exclude \(aq*.pyc\(aq
 
 # Backup home directories excluding image thumbnails (i.e. only
-# /home/*/.thumbnails is excluded, not /home/*/*/.thumbnails)
-$ borg create /path/to/repo::my\-files /home \e
-    \-\-exclude \(aqre:^/home/[^/]+/\e.thumbnails/\(aq
-
-# Do the same using a shell\-style pattern
+# /home/<one directory>/.thumbnails is excluded, not /home/*/*/.thumbnails etc.)
 $ borg create /path/to/repo::my\-files /home \e
     \-\-exclude \(aqsh:/home/*/.thumbnails\(aq
 
@@ -238,8 +237,8 @@ $ borg create /path/to/repo::daily\-projectA\-{now:%Y\-%m\-%d} projectA
 .UNINDENT
 .SH NOTES
 .sp
-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
+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.
 .sp

docs/man/borg-delete.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-DELETE 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .
@@ -66,7 +66,10 @@ work slower, but using less space
 .INDENT 0.0
 .TP
 .B \-P\fP,\fB  \-\-prefix
-only consider archive names starting with this prefix
+only consider archive names starting with this prefix.
+.TP
+.B \-a\fP,\fB  \-\-glob\-archives
+only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
 .TP
 .B \-\-sort\-by
 Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp

docs/man/borg-diff.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DIFF 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-DIFF 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .
@@ -47,7 +47,7 @@ are compared, which is very fast.
 .sp
 For archives prior to Borg 1.1 chunk contents are compared by default.
 If you did not create the archives with different chunker params,
-pass \-\-same\-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.
@@ -97,10 +97,10 @@ exclude directories that are tagged by containing a filesystem object with the g
 if tag objects are specified with \-\-exclude\-if\-present, don\(aqt omit the tag objects themselves from the backup archive
 .TP
 .BI \-\-pattern \ PATTERN
-include/exclude paths matching PATTERN
+experimental: include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-read include/exclude patterns from PATTERNFILE, one per line
+experimental: read include/exclude patterns from PATTERNFILE, one per line
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0

docs/man/borg-export-tar.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXPORT-TAR 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .
@@ -39,7 +39,7 @@ This command creates a tarball from an archive.
 .sp
 When giving \(aq\-\(aq as the output FILE, Borg will write a tar stream to standard output.
 .sp
-By default (\-\-tar\-filter=auto) Borg will detect whether the FILE should be compressed
+By default (\fB\-\-tar\-filter=auto\fP) Borg will detect whether the FILE should be compressed
 based on its file extension and pipe the tarball through an appropriate filter
 before writing it to FILE:
 .INDENT 0.0
@@ -51,7 +51,7 @@ before writing it to FILE:
 \&.tar.xz: xz
 .UNINDENT
 .sp
-Alternatively a \-\-tar\-filter program may be explicitly specified. It should
+Alternatively a \fB\-\-tar\-filter\fP program may be explicitly specified. It should
 read the uncompressed tar stream from stdin and write a compressed/filtered
 tar stream to stdout.
 .sp
@@ -62,7 +62,7 @@ BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported.
 Timestamp resolution is limited to whole seconds, not the nanosecond resolution
 otherwise supported by Borg.
 .sp
-A \-\-sparse option (as found in borg extract) is not supported.
+A \fB\-\-sparse\fP option (as found in borg extract) is not supported.
 .sp
 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.
@@ -103,10 +103,10 @@ exclude paths matching PATTERN
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
 .BI \-\-pattern \ PATTERN
-include/exclude paths matching PATTERN
+experimental: include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-read include/exclude patterns from PATTERNFILE, one per line
+experimental: read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .BI \-\-strip\-components \ NUMBER
 Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.

docs/man/borg-extract.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXTRACT 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .
@@ -76,10 +76,10 @@ exclude paths matching PATTERN
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
 .BI \-\-pattern \ PATTERN
-include/exclude paths matching PATTERN
+experimental: include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-read include/exclude patterns from PATTERNFILE, one per line
+experimental: read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .B \-\-numeric\-owner
 only obey numeric user and group identifiers

docs/man/borg-info.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INFO 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-INFO 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .
@@ -67,7 +67,10 @@ format output as JSON
 .INDENT 0.0
 .TP
 .B \-P\fP,\fB  \-\-prefix
-only consider archive names starting with this prefix
+only consider archive names starting with this prefix.
+.TP
+.B \-a\fP,\fB  \-\-glob\-archives
+only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
 .TP
 .B \-\-sort\-by
 Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp

docs/man/borg-init.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INIT 1 "2017-06-11" "" "borg backup tool"
+.TH BORG-INIT 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .
@@ -81,6 +81,8 @@ a different keyboard layout.
 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
+.\" nanorst: inline-fill
+.
 .TS
 center;
 |l|l|l|l|.
@@ -103,9 +105,10 @@ SHA\-256
 T}	T{
 none
 T}	T{
-authenticated
+\fIauthenticated\fP
 T}	T{
-repokey, keyfile
+repokey
+keyfile
 T}
 _
 T{
@@ -113,17 +116,22 @@ BLAKE2b
 T}	T{
 n/a
 T}	T{
-authenticated\-blake2
+\fIauthenticated\-blake2\fP
 T}	T{
-repokey\-blake2,
-keyfile\-blake2
+\fIrepokey\-blake2\fP
+\fIkeyfile\-blake2\fP
 T}
 _
 .TE
+.\" nanorst: inline-replace
+.
+.sp
+\fIMarked modes\fP are new in Borg 1.1 and are not backwards\-compatible with Borg 1.0.x.
 .sp
 On modern Intel/AMD CPUs (except very cheap ones), AES is usually
 hardware\-accelerated.
-BLAKE2b is faster than SHA256 on Intel/AMD 64\-bit CPUs,
+BLAKE2b is faster than SHA256 on Intel/AMD 64\-bit CPUs
+(except AMD Ryzen and future CPUs with SHA extensions),
 which makes \fIauthenticated\-blake2\fP faster than \fInone\fP and \fIauthenticated\fP\&.
 .sp
 On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
@@ -134,7 +142,7 @@ Hardware acceleration is always used automatically when available.
 \fIrepokey\fP and \fIkeyfile\fP use AES\-CTR\-256 for encryption and HMAC\-SHA256 for
 authentication in an encrypt\-then\-MAC (EtM) construction. The chunk ID hash
 is HMAC\-SHA256 as well (with a separate key).
-These modes are compatible with borg 1.0.x.
+These modes are compatible with Borg 1.0.x.
 .sp
 \fIrepokey\-blake2\fP and \fIkeyfile\-blake2\fP are also authenticated encryption modes,
 but use BLAKE2b\-256 instead of HMAC\-SHA256 for authentication. The chunk ID
@@ -144,7 +152,7 @@ These modes are new and \fInot\fP compatible with Borg 1.0.x.
 \fIauthenticated\fP mode uses no encryption, but authenticates repository contents
 through the same HMAC\-SHA256 hash as the \fIrepokey\fP and \fIkeyfile\fP modes (it uses it
 as the chunk ID hash). The key is stored like \fIrepokey\fP\&.
-This mode is new and \fInot\fP compatible with borg 1.0.x.
+This mode is new and \fInot\fP compatible with Borg 1.0.x.
 .sp
 \fIauthenticated\-blake2\fP is like \fIauthenticated\fP, but uses the keyed BLAKE2b\-256 hash
 from the other blake2 modes.
@@ -152,7 +160,8 @@ This mode is new and \fInot\fP compatible with Borg 1.0.x.
 .sp
 \fInone\fP mode uses no encryption and no authentication. It uses SHA256 as chunk
 ID hash. Not recommended, rather consider using an authenticated or
-authenticated/encrypted mode.
+authenticated/encrypted mode. This mode has possible denial\-of\-service issues
+when running \fBborg create\fP on contents controlled by an attacker.
 Use it only for new repositories where no encryption is wanted \fBand\fP when compatibility
 with 1.0.x is important. If compatibility with 1.0.x is not important, use
 \fIauthenticated\-blake2\fP or \fIauthenticated\fP instead.
@@ -172,7 +181,7 @@ repository to create
 .B \-e\fP,\fB  \-\-encryption
 select encryption key mode \fB(required)\fP
 .TP
-.B \-a\fP,\fB  \-\-append\-only
+.B \-\-append\-only
 create an append\-only mode repository
 .TP
 .B \-\-storage\-quota

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

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .
@@ -43,6 +43,50 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .sp
 REPOSITORY
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Create a key file protected repository
+$ borg init \-\-encryption=keyfile \-v /path/to/repo
+Initializing repository at "/path/to/repo"
+Enter new passphrase:
+Enter same passphrase again:
+Remember your passphrase. Your data will be inaccessible without it.
+Key in "/root/.config/borg/keys/mnt_backup" created.
+Keep this key safe. Your data will be inaccessible without it.
+Synchronizing chunks cache...
+Archives: 0, w/ cached Idx: 0, w/ outdated Idx: 0, w/o cached Idx: 0.
+Done.
+
+# Change key file passphrase
+$ borg key change\-passphrase \-v /path/to/repo
+Enter passphrase for key /root/.config/borg/keys/mnt_backup:
+Enter new passphrase:
+Enter same passphrase again:
+Remember your passphrase. Your data will be inaccessible without it.
+Key updated
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Fully automated using environment variables:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ BORG_NEW_PASSPHRASE=old borg init \-e=repokey repo
+# now "old" is the current passphrase.
+$ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase repo
+# now "new" is the current passphrase.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP

docs/man/borg-key-export.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-EXPORT 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .

docs/man/borg-key-import.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-IMPORT 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .
@@ -56,7 +56,7 @@ path to the backup
 .INDENT 0.0
 .TP
 .B \-\-paper
-interactively import from a backup done with \-\-paper
+interactively import from a backup done with \fB\-\-paper\fP
 .UNINDENT
 .SH SEE ALSO
 .sp

docs/man/borg-key-migrate-to-repokey.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .

docs/man/borg-key.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-KEY 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-key \- Manage a keyfile or repokey of a repository
 .

docs/man/borg-list.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-LIST 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-LIST 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .
@@ -61,16 +61,19 @@ specify format for file listing
 (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
 .TP
 .B \-\-json
-Only valid for listing repository contents. Format output as JSON. The form of \-\-format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
+Only valid for listing repository contents. Format output as JSON. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
 .TP
 .B \-\-json\-lines
-Only valid for listing archive contents. Format output as JSON Lines. The form of \-\-format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
+Only valid for listing archive contents. Format output as JSON Lines. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
 .UNINDENT
 .SS filters
 .INDENT 0.0
 .TP
 .B \-P\fP,\fB  \-\-prefix
-only consider archive names starting with this prefix
+only consider archive names starting with this prefix.
+.TP
+.B \-a\fP,\fB  \-\-glob\-archives
+only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
 .TP
 .B \-\-sort\-by
 Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
@@ -100,10 +103,10 @@ exclude directories that are tagged by containing a filesystem object with the g
 if tag objects are specified with \-\-exclude\-if\-present, don\(aqt omit the tag objects themselves from the backup archive
 .TP
 .BI \-\-pattern \ PATTERN
-include/exclude paths matching PATTERN
+experimental: include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-read include/exclude patterns from PATTERNFILE, one per line
+experimental: read include/exclude patterns from PATTERNFILE, one per line
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
@@ -138,9 +141,7 @@ drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code/myproject
 .UNINDENT
 .SH NOTES
 .sp
-The following keys are available for \-\-format:
-.INDENT 0.0
-.INDENT 3.5
+The following keys are available for \fB\-\-format\fP:
 .INDENT 0.0
 .IP \(bu 2
 NEWLINE: OS dependent line separator
@@ -157,13 +158,9 @@ CR
 .IP \(bu 2
 LF
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 Keys for listing repository archives:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 archive, name: archive name interpreted as text (might be missing non\-text characters, see barchive)
 .IP \(bu 2
@@ -173,13 +170,9 @@ time: time of creation of the archive
 .IP \(bu 2
 id: internal ID of the archive
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .sp
 Keys for listing archive files:
 .INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
 .IP \(bu 2
 type
 .IP \(bu 2
@@ -247,8 +240,6 @@ extra: prepends {source} with " \-> " for soft links and " link to " for hard li
 .IP \(bu 2
 health: either "healthy" (file ok) or "broken" (if file has all\-zero replacement chunks)
 .UNINDENT
-.UNINDENT
-.UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-info(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-patterns(1)\fP

docs/man/borg-mount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .
@@ -55,7 +55,7 @@ versions: when used with a repository mount, this gives a merged, versioned
 view of the files in the archives. EXPERIMENTAL, layout may change in future.
 .IP \(bu 2
 allow_damaged_files: by default damaged files (where missing chunks were
-replaced with runs of zeros by borg check \-\-repair) are not readable and
+replaced with runs of zeros by borg check \fB\-\-repair\fP) are not readable and
 return EIO (I/O error). Set this option to read such files.
 .UNINDENT
 .sp
@@ -95,7 +95,10 @@ Extra mount options
 .INDENT 0.0
 .TP
 .B \-P\fP,\fB  \-\-prefix
-only consider archive names starting with this prefix
+only consider archive names starting with this prefix.
+.TP
+.B \-a\fP,\fB  \-\-glob\-archives
+only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
 .TP
 .B \-\-sort\-by
 Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp

docs/man/borg-patterns.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .
@@ -34,16 +34,17 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .sp
 File patterns support these styles: fnmatch, shell, regular expressions,
 path prefixes and path full\-matches. By default, fnmatch is used for
-\fI\-\-exclude\fP patterns and shell\-style is used for \fI\-\-pattern\fP\&. If followed
-by a colon (\(aq:\(aq) the first two characters of a pattern are used as a
+\fB\-\-exclude\fP patterns and shell\-style is used for the experimental \fB\-\-pattern\fP
+option.
+.sp
+If followed by a colon (\(aq:\(aq) the first two characters of a pattern are used as a
 style selector. Explicit style selection is necessary when a
 non\-default style is desired or when the desired pattern starts with
 two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP).
-.sp
-\fI\%Fnmatch\fP, selector \fIfm:\fP
 .INDENT 0.0
-.INDENT 3.5
-This is the default style for \-\-exclude and \-\-exclude\-from.
+.TP
+.B \fI\%Fnmatch\fP, selector \fIfm:\fP
+This is the default style for \fB\-\-exclude\fP and \fB\-\-exclude\-from\fP\&.
 These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching
 any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq
 matching any single character specified, including ranges, and \(aq[!...]\(aq
@@ -56,23 +57,15 @@ must match from the start to just before a path separator. Except
 for the root path, paths will never end in the path separator when
 matching is attempted.  Thus, if a given pattern ends in a path
 separator, a \(aq*\(aq is appended before matching is attempted.
-.UNINDENT
-.UNINDENT
-.sp
-Shell\-style patterns, selector \fIsh:\fP
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B Shell\-style patterns, selector \fIsh:\fP
 This is the default style for \-\-pattern and \-\-patterns\-from.
 Like fnmatch patterns these are similar to shell patterns. The difference
 is that the pattern may include \fI**/\fP for matching zero or more directory
 levels, \fI*\fP for matching zero or more arbitrary characters with the
 exception of any path separator.
-.UNINDENT
-.UNINDENT
-.sp
-Regular expressions, selector \fIre:\fP
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B Regular expressions, selector \fIre:\fP
 Regular expressions similar to those found in Perl are supported. Unlike
 shell patterns regular expressions are not required to match the complete
 path and any substring match is sufficient. It is strongly recommended to
@@ -81,20 +74,12 @@ separators (\(aq\(aq for Windows and \(aq/\(aq on other systems) in paths are
 always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The
 regular expression syntax is described in the \fI\%Python documentation for
 the re module\fP\&.
-.UNINDENT
-.UNINDENT
-.sp
-Path prefix, selector \fIpp:\fP
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B Path prefix, selector \fIpp:\fP
 This pattern style is useful to match whole sub\-directories. The pattern
 \fIpp:/data/bar\fP matches \fI/data/bar\fP and everything therein.
-.UNINDENT
-.UNINDENT
-.sp
-Path full\-match, selector \fIpf:\fP
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B Path full\-match, selector \fIpf:\fP
 This pattern style is useful to match whole paths.
 This is kind of a pseudo pattern as it can not have any variable or
 unspecified parts \- the full, precise path must be given.
@@ -109,13 +94,24 @@ If you use such a pattern to include a file, it will always be included
 Other include/exclude patterns that would normally match will be ignored.
 Same logic applies for exclude.
 .UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+\fIre:\fP, \fIsh:\fP and \fIfm:\fP patterns are all implemented on top of the Python SRE
+engine. It is very easy to formulate patterns for each of these types which
+requires an inordinate amount of time to match paths. If untrusted users
+are able to supply patterns, ensure they cannot supply \fIre:\fP patterns.
+Further, ensure that \fIsh:\fP and \fIfm:\fP patterns only contain a handful of
+wildcards at most.
+.UNINDENT
 .UNINDENT
 .sp
-Exclusions can be passed via the command line option \fI\-\-exclude\fP\&. When used
+Exclusions can be passed via the command line option \fB\-\-exclude\fP\&. When used
 from within a shell the patterns should be quoted to protect them from
 expansion.
 .sp
-The \fI\-\-exclude\-from\fP option permits loading exclusion patterns from a text
+The \fB\-\-exclude\-from\fP option permits loading exclusion patterns from a text
 file with one pattern per line. Lines empty or starting with the number sign
 (\(aq#\(aq) after removing whitespace on both ends are ignored. The optional style
 selector prefix is also supported for patterns loaded from a file. Due to
@@ -159,26 +155,25 @@ $ borg create \-\-exclude\-from exclude.txt backup /
 .fi
 .UNINDENT
 .UNINDENT
-.sp
 A more general and easier to use way to define filename matching patterns exists
-with the \fI\-\-pattern\fP and \fI\-\-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 \fIR\fP, followed by a path (a plain path, not a
+with the experimental \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 \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 \-, both followed by a pattern.
 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.
 .sp
-Note that the default pattern style for \fI\-\-pattern\fP and \fI\-\-patterns\-from\fP is
+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 (\fI\-\-pattern\fP) and excludes (\fI\-\-exclude\fP) from the command line are
-considered first (in the order of appearance). Then patterns from \fI\-\-patterns\-from\fP
-are added. Exclusion patterns from \fI\-\-exclude\-from\fP files are appended last.
+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
-An example \fI\-\-patterns\-from\fP file could look like that:
+An example \fB\-\-patterns\-from\fP file could look like that:
 .INDENT 0.0
 .INDENT 3.5
 .sp

docs/man/borg-placeholders.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PLACEHOLDERS 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .
@@ -32,80 +32,42 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH DESCRIPTION
 .sp
-Repository (or Archive) URLs, \-\-prefix and \-\-remote\-path values support these
+Repository (or Archive) URLs, \fB\-\-prefix\fP and \fB\-\-remote\-path\fP values support these
 placeholders:
-.sp
-{hostname}
 .INDENT 0.0
-.INDENT 3.5
+.TP
+.B {hostname}
 The (short) hostname of the machine.
-.UNINDENT
-.UNINDENT
-.sp
-{fqdn}
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B {fqdn}
 The full name of the machine.
-.UNINDENT
-.UNINDENT
-.sp
-{now}
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B {now}
 The current local date and time, by default in ISO\-8601 format.
 You can also supply your own \fI\%format string\fP, e.g. {now:%Y\-%m\-%d_%H:%M:%S}
-.UNINDENT
-.UNINDENT
-.sp
-{utcnow}
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B {utcnow}
 The current UTC date and time, by default in ISO\-8601 format.
 You can also supply your own \fI\%format string\fP, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
-.UNINDENT
-.UNINDENT
-.sp
-{user}
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B {user}
 The user name (or UID, if no name is available) of the user running borg.
-.UNINDENT
-.UNINDENT
-.sp
-{pid}
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B {pid}
 The current process ID.
-.UNINDENT
-.UNINDENT
-.sp
-{borgversion}
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B {borgversion}
 The version of borg, e.g.: 1.0.8rc1
-.UNINDENT
-.UNINDENT
-.sp
-{borgmajor}
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B {borgmajor}
 The version of borg, only the major version, e.g.: 1
-.UNINDENT
-.UNINDENT
-.sp
-{borgminor}
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B {borgminor}
 The version of borg, only major and minor version, e.g.: 1.0
-.UNINDENT
-.UNINDENT
-.sp
-{borgpatch}
-.INDENT 0.0
-.INDENT 3.5
+.TP
+.B {borgpatch}
 The version of borg, only major, minor and patch version, e.g.: 1.0.8
 .UNINDENT
-.UNINDENT
 .sp
 If literal curly braces need to be used, double them for escaping:
 .INDENT 0.0
@@ -132,6 +94,20 @@ borg prune \-\-prefix \(aq{hostname}\-\(aq ...
 .fi
 .UNINDENT
 .UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+systemd uses a difficult, non\-standard syntax for command lines in unit files (refer to
+the \fIsystemd.unit(5)\fP manual page).
+.sp
+When invoking borg from unit files, pay particular attention to escaping,
+especially when using the now/utcnow placeholders, since systemd performs its own
+%\-based variable replacement even in quoted text. To avoid interference from systemd,
+double all percent signs (\fB{hostname}\-{now:%Y\-%m\-%d_%H:%M:%S}\fP
+becomes \fB{hostname}\-{now:%%Y\-%%m\-%%d_%%H:%%M:%%S}\fP).
+.UNINDENT
+.UNINDENT
 .SH AUTHOR
 The Borg Collective
 .\" Generated by docutils manpage writer.

docs/man/borg-prune.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PRUNE 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .
@@ -42,7 +42,7 @@ automated backup scripts wanting to keep a certain number of historic backups.
 Also, prune automatically removes checkpoint archives (incomplete archives left
 behind by interrupted backup runs) except if the checkpoint is the latest
 archive (and thus still needed). Checkpoint archives are not considered when
-comparing archive counts against the retention limits (\-\-keep\-X).
+comparing archive counts against the retention limits (\fB\-\-keep\-X\fP).
 .sp
 If a prefix is set with \-P, then only archives that start with the prefix are
 considered for deletion and only those archives count towards the totals
@@ -55,14 +55,14 @@ If you have multiple sequences of archives with different data sets (e.g.
 from different machines) in one shared repository, use one prune call per
 data set that matches only the respective archives using the \-P option.
 .sp
-The "\-\-keep\-within" option takes an argument of the form "<int><char>",
-where char is "H", "d", "w", "m", "y". For example, "\-\-keep\-within 2d" means
+The \fB\-\-keep\-within\fP option takes an argument of the form "<int><char>",
+where char is "H", "d", "w", "m", "y". For example, \fB\-\-keep\-within 2d\fP means
 to keep all archives that were created within the past 48 hours.
 "1m" is taken to mean "31d". The archives kept with this option do not
 count towards the totals specified by any other options.
 .sp
 A good procedure is to thin out more and more the older your backups get.
-As an example, "\-\-keep\-daily 7" means to keep the latest backup on each day,
+As an example, \fB\-\-keep\-daily 7\fP means to keep the latest backup on each day,
 up to 7 most recent days with backups (days without backups do not count).
 The rules are applied from secondly to yearly, and backups selected by previous
 rules do not count towards those of later rules. The time that each backup
@@ -70,7 +70,7 @@ starts is used for pruning purposes. Dates and times are interpreted in
 the local timezone, and weeks go from Monday to Sunday. Specifying a
 negative number of archives to keep means that there is no limit.
 .sp
-The "\-\-keep\-last N" option is doing the same as "\-\-keep\-secondly N" (and it will
+The \fB\-\-keep\-last N\fP option is doing the same as \fB\-\-keep\-secondly N\fP (and it will
 keep the last N archives under the assumption that you do not create more than one
 backup archive in the same second).
 .SH OPTIONS
@@ -121,12 +121,18 @@ number of monthly archives to keep
 .B \-y\fP,\fB  \-\-keep\-yearly
 number of yearly archives to keep
 .TP
-.B \-P\fP,\fB  \-\-prefix
-only consider archive names starting with this prefix
-.TP
 .B \-\-save\-space
 work slower, but using less space
 .UNINDENT
+.SS filters
+.INDENT 0.0
+.TP
+.B \-P\fP,\fB  \-\-prefix
+only consider archive names starting with this prefix.
+.TP
+.B \-a\fP,\fB  \-\-glob\-archives
+only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+.UNINDENT
 .SH EXAMPLES
 .sp
 Be careful, prune is a potentially dangerous command, it will remove backup

docs/man/borg-recreate.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RECREATE 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .
@@ -39,33 +39,33 @@ Recreate the contents of existing archives.
 .sp
 This is an \fIexperimental\fP feature. Do \fInot\fP use this on your only backup.
 .sp
-\-\-exclude, \-\-exclude\-from, \-\-exclude\-if\-present, \-\-keep\-exclude\-tags, and PATH
+\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, \fB\-\-exclude\-if\-present\fP, \fB\-\-keep\-exclude\-tags\fP, and PATH
 have the exact same semantics as in "borg create". If PATHs are specified the
 resulting archive will only contain files from these PATHs.
 .sp
 Note that all paths in an archive are relative, therefore absolute patterns/paths
-will \fInot\fP match (\-\-exclude, \-\-exclude\-from, PATHs).
+will \fInot\fP match (\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, PATHs).
 .sp
-\-\-recompress allows to change the compression of existing data in archives.
+\fB\-\-recompress\fP allows to change the compression of existing data in archives.
 Due to how Borg stores compressed size information this might display
 incorrect information for archives that were not recreated at the same time.
 There is no risk of data loss by this.
 .sp
-\-\-chunker\-params will re\-chunk all files in the archive, this can be
+\fB\-\-chunker\-params\fP will re\-chunk all files in the archive, this can be
 used to have upgraded Borg 0.xx or Attic archives deduplicate with
 Borg 1.x archives.
 .sp
-USE WITH CAUTION.
+\fBUSE WITH CAUTION.\fP
 Depending on the PATHs and patterns given, recreate can be used to permanently
 delete files from archives.
-When in doubt, use "\-\-dry\-run \-\-verbose \-\-list" to see how patterns/PATHS are
+When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHS are
 interpreted.
 .sp
 The archive being recreated is only removed after the operation completes. The
 archive that is built during the operation exists at the same time at
 "<ARCHIVE>.recreate". The new archive will have a different archive ID.
 .sp
-With \-\-target the original archive is not replaced, instead a new archive is created.
+With \fB\-\-target\fP the original archive is not replaced, instead a new archive is created.
 .sp
 When rechunking space usage can be substantial, expect at least the entire
 deduplicated size of the archives using the previous chunker params.
@@ -114,13 +114,13 @@ exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosauru
 exclude directories that are tagged by containing a filesystem object with the given NAME
 .TP
 .B \-\-keep\-exclude\-tags\fP,\fB  \-\-keep\-tag\-files
-if tag objects are specified with \-\-exclude\-if\-present, don\(aqt omit the tag objects themselves from the backup archive
+if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive
 .TP
 .BI \-\-pattern \ PATTERN
-include/exclude paths matching PATTERN
+experimental: include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-read include/exclude patterns from PATTERNFILE, one per line
+experimental: read include/exclude patterns from PATTERNFILE, one per line
 .UNINDENT
 .SS Archive options
 .INDENT 0.0
@@ -141,10 +141,10 @@ manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss form
 select compression algorithm, see the output of the "borg help compression" command for details.
 .TP
 .B \-\-recompress
-recompress data chunks according to \-\-compression if "if\-different". When "always", chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for "if\-different", not the compression level (if any).
+recompress data chunks according to \fB\-\-compression\fP if \fIif\-different\fP\&. When \fIalways\fP, chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for \fIif\-different\fP, not the compression level (if any).
 .TP
 .BI \-\-chunker\-params \ PARAMS
-specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or "default" to use the current defaults. default: 19,23,21,4095
+specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the current defaults. default: 19,23,21,4095
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0

docs/man/borg-rename.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RENAME 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-RENAME 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .

docs/man/borg-serve.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-SERVE 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-SERVE 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .
@@ -45,8 +45,14 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .BI \-\-restrict\-to\-path \ PATH
 restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to directly point to a repository.
 .TP
+.BI \-\-restrict\-to\-repository \ PATH
+restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \-\-restrict\-to\-path sub\-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
+.TP
 .B \-\-append\-only
 only allow appending to repository segment files
+.TP
+.B \-\-storage\-quota
+Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.
 .UNINDENT
 .SH EXAMPLES
 .sp

docs/man/borg-umount.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UMOUNT 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-UMOUNT 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .
@@ -101,7 +101,7 @@ bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt  root  sbin  s
 .INDENT 0.0
 .INDENT 3.5
 \fBborgfs\fP will be automatically provided if you used a distribution
-package, \fBpip\fP or \fBsetup.py\fP to install Borg\&. Users of the
+package, \fBpip\fP or \fBsetup.py\fP to install Borg. Users of the
 standalone binary will have to manually create a symlink (see
 \fIpyinstaller\-binary\fP).
 .UNINDENT

docs/man/borg-upgrade.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UPGRADE 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .
@@ -132,7 +132,7 @@ path to the repository to be upgraded
 .B \-n\fP,\fB  \-\-dry\-run
 do not change repository
 .TP
-.B \-i\fP,\fB  \-\-inplace
+.B \-\-inplace
 rewrite repository in place, with no chance of going back to older
 versions of the repository.
 .TP

docs/man/borg-with-lock.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-WITH-LOCK 1 "2017-05-17" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2017-06-18" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .

docs/man/borg.1

@@ -259,7 +259,7 @@ If you have set BORG_REPO (see above) and an archive location is needed, use
 The log level of the builtin logging configuration defaults to WARNING.
 This is because we want Borg to be mostly silent and only output
 warnings, errors and critical messages, unless output has been requested
-by supplying an option that implies output (eg, \-\-list or \-\-progress).
+by supplying an option that implies output (e.g. \fB\-\-list\fP or \fB\-\-progress\fP).
 .sp
 Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
 .sp
@@ -284,28 +284,50 @@ give different output on different log levels \- it\(aqs just a possibility.
 \fBWARNING:\fP
 .INDENT 0.0
 .INDENT 3.5
-Options \-\-critical and \-\-error are provided for completeness,
+Options \fB\-\-critical\fP and \fB\-\-error\fP are provided for completeness,
 their usage is not recommended as you might miss important information.
 .UNINDENT
 .UNINDENT
 .SS Return codes
 .sp
 Borg can exit with the following return codes (rc):
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-0 = success (logged as INFO)
-1 = warning (operation reached its normal end, but there were warnings \-
-    you should check the log, logged as WARNING)
-2 = error (like a fatal error, a local or remote exception, the operation
-    did not reach its normal end, logged as ERROR)
-128+N = killed by signal N (e.g. 137 == kill \-9)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
+.TS
+center;
+|l|l|.
+_
+T{
+Return code
+T}	T{
+Meaning
+T}
+_
+T{
+0
+T}	T{
+success (logged as INFO)
+T}
+_
+T{
+1
+T}	T{
+warning (operation reached its normal end, but there were warnings \-\-
+you should check the log, logged as WARNING)
+T}
+_
+T{
+2
+T}	T{
+error (like a fatal error, a local or remote exception, the operation
+did not reach its normal end, logged as ERROR)
+T}
+_
+T{
+128+N
+T}	T{
+killed by signal N (e.g. 137 == kill \-9)
+T}
+_
+.TE
 .sp
 If you use \fB\-\-show\-rc\fP, the return code is also logged at the indicated
 level as the last log entry.
@@ -319,18 +341,27 @@ Borg uses some environment variables for automation:
 .TP
 .B BORG_REPO
 When set, use the value to give the default repository location. If a command needs an archive
-parameter, you can abbreviate as \fI::archive\fP\&. If a command needs a repository parameter, you
-can either leave it away or abbreviate as \fI::\fP, if a positional parameter is required.
+parameter, you can abbreviate as \fB::archive\fP\&. If a command needs a repository parameter, you
+can either leave it away or abbreviate as \fB::\fP, if a positional parameter is required.
 .TP
 .B BORG_PASSPHRASE
 When set, use the value to answer the passphrase question for encrypted repositories.
-It is used when a passphrase is needed to access a encrypted repo as well as when a new
+It is used when a passphrase is needed to access an encrypted repo as well as when a new
+passphrase should be initially set when initializing an encrypted repo.
+See also BORG_NEW_PASSPHRASE.
+.TP
+.B BORG_PASSCOMMAND
+When set, use the standard output of the command (trailing newlines are stripped) to answer the
+passphrase question for encrypted repositories.
+It is used when a passphrase is needed to access an encrypted repo as well as when a new
 passphrase should be initially set when initializing an encrypted repo.
+If BORG_PASSPHRASE is also set, it takes precedence.
 See also BORG_NEW_PASSPHRASE.
 .TP
 .B BORG_NEW_PASSPHRASE
 When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for.
-This variable is checked first. If it is not set, BORG_PASSPHRASE will be checked also.
+This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also
+be checked.
 Main usecase for this is to fully automate \fBborg change\-passphrase\fP\&.
 .TP
 .B BORG_DISPLAY_PASSPHRASE
@@ -537,7 +568,7 @@ depending on archive count and size \- see FAQ about how to reduce).
 .TP
 .B Network (only for client/server operation):
 If your repository is remote, all deduplicated (and optionally compressed/
-encrypted) data of course has to go over the connection (ssh: repo url).
+encrypted) data of course has to go over the connection (\fBssh://\fP repo url).
 If you use a locally mounted network filesystem, additionally some copy
 operations used for transaction support also go over the connection. If
 you backup multiple sources to one target repository, additional traffic

docs/usage/create.rst.inc

@@ -25,6 +25,8 @@ optional arguments
         | only display items with the given status characters
     ``--json``
         | output stats as JSON (implies --stats)
+    ``--no-cache-sync``
+        | experimental: do not synchronize the cache. Implies --no-files-cache.
 
 :ref:`common_options`
     |

docs/usage/help.rst.inc

@@ -8,7 +8,7 @@ borg help patterns
 
 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 experimental `--pattern`
+``--exclude`` patterns and shell-style is used for the experimental ``--pattern``
 option.
 
 If followed by a colon (':') the first two characters of a pattern are used as a
@@ -17,8 +17,7 @@ non-default style is desired or when the desired pattern starts with
 two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
 
 `Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`
-
-    This is the default style for --exclude and --exclude-from.
+    This is the default style for ``--exclude`` and ``--exclude-from``.
     These patterns use a variant of shell pattern syntax, with '\*' matching
     any number of characters, '?' matching any single character, '[...]'
     matching any single character specified, including ranges, and '[!...]'
@@ -33,7 +32,6 @@ two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
     separator, a '\*' is appended before matching is attempted.
 
 Shell-style patterns, selector `sh:`
-
     This is the default style for --pattern and --patterns-from.
     Like fnmatch patterns these are similar to shell patterns. The difference
     is that the pattern may include `**/` for matching zero or more directory
@@ -41,7 +39,6 @@ Shell-style patterns, selector `sh:`
     exception of any path separator.
 
 Regular expressions, selector `re:`
-
     Regular expressions similar to those found in Perl are supported. Unlike
     shell patterns regular expressions are not required to match the complete
     path and any substring match is sufficient. It is strongly recommended to
@@ -52,12 +49,10 @@ Regular expressions, selector `re:`
     the re module <https://docs.python.org/3/library/re.html>`_.
 
 Path prefix, selector `pp:`
-
     This pattern style is useful to match whole sub-directories. The pattern
     `pp:/data/bar` matches `/data/bar` and everything therein.
 
 Path full-match, selector `pf:`
-
     This pattern style is useful to match whole paths.
     This is kind of a pseudo pattern as it can not have any variable or
     unspecified parts - the full, precise path must be given.
@@ -81,11 +76,11 @@ Path full-match, selector `pf:`
     Further, ensure that `sh:` and `fm:` patterns only contain a handful of
     wildcards at most.
 
-Exclusions can be passed via the command line option `--exclude`. When used
+Exclusions can be passed via the command line option ``--exclude``. When used
 from within a shell the patterns should be quoted to protect them from
 expansion.
 
-The `--exclude-from` option permits loading exclusion patterns from a text
+The ``--exclude-from`` option permits loading exclusion patterns from a text
 file with one pattern per line. Lines empty or starting with the number sign
 ('#') after removing whitespace on both ends are ignored. The optional style
 selector prefix is also supported for patterns loaded from a file. Due to
@@ -125,7 +120,7 @@ Examples::
 .. container:: experimental
 
     A more general and easier to use way to define filename matching patterns exists
-    with the experimental `--pattern` and `--patterns-from` options. Using these, you
+    with the experimental ``--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
@@ -134,15 +129,15 @@ Examples::
     path. The first matching pattern is used so if an include pattern matches before
     an exclude pattern, the file is backed up.
 
-    Note that the default pattern style for `--pattern` and `--patterns-from` is
+    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.
+    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.
 
-    An example `--patterns-from` file could look like that::
+    An example ``--patterns-from`` file could look like that::
 
         # "sh:" pattern style is the default, so the following line is not needed:
         P sh
@@ -163,49 +158,39 @@ borg help placeholders
 ~~~~~~~~~~~~~~~~~~~~~~
 
 
-Repository (or Archive) URLs, --prefix and --remote-path values support these
+Repository (or Archive) URLs, ``--prefix`` and ``--remote-path`` values support these
 placeholders:
 
 {hostname}
-
     The (short) hostname of the machine.
 
 {fqdn}
-
     The full name of the machine.
 
 {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.4/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.4/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.
 
 {pid}
-
     The current process ID.
 
 {borgversion}
-
     The version of borg, e.g.: 1.0.8rc1
 
 {borgmajor}
-
     The version of borg, only the major version, e.g.: 1
 
 {borgminor}
-
     The version of borg, only major and minor version, e.g.: 1.0
 
 {borgpatch}
-
     The version of borg, only major, minor and patch version, e.g.: 1.0.8
 
 If literal curly braces need to be used, double them for escaping::
@@ -234,20 +219,26 @@ borg help compression
 ~~~~~~~~~~~~~~~~~~~~~
 
 
+It is no problem to mix different compression methods in one repo,
+deduplication is done on the source data chunks (not on the compressed
+or encrypted data).
+
+If some specific chunk was once compressed and stored into the repo, creating
+another backup that also uses this chunk will not change the stored chunk.
+So if you use different compression specs for the backups, whichever stores a
+chunk first determines its compression. See also borg recreate.
+
 Compression is lz4 by default. If you want something else, you have to specify what you want.
 
 Valid compression specifiers are:
 
 none
-
     Do not compress.
 
 lz4
-
     Use lz4 compression. High speed, low compression. (default)
 
 zlib[,L]
-
     Use zlib ("gz") compression. Medium speed, medium compression.
     If you do not explicitely give the compression level L (ranging from 0
     to 9), it will use level 6.
@@ -255,7 +246,6 @@ zlib[,L]
     overhead) is usually pointless, you better use "none" compression.
 
 lzma[,L]
-
     Use lzma ("xz") compression. Low speed, high compression.
     If you do not explicitely give the compression level L (ranging from 0
     to 9), it will use level 6.
@@ -264,7 +254,6 @@ lzma[,L]
     lots of CPU cycles and RAM.
 
 auto,C[,L]
-
     Use a built-in heuristic to decide per chunk whether to compress or not.
     The heuristic tries with lz4 whether the data is compressible.
     For incompressible data, it will not use compression (uses "none").
@@ -279,14 +268,3 @@ Examples::
     borg create --compression auto,lzma,6 REPO::ARCHIVE data
     borg create --compression auto,lzma ...
 
-General remarks:
-
-It is no problem to mix different compression methods in one repo,
-deduplication is done on the source data chunks (not on the compressed
-or encrypted data).
-
-If some specific chunk was once compressed and stored into the repo, creating
-another backup that also uses this chunk will not change the stored chunk.
-So if you use different compression specs for the backups, whichever stores a
-chunk first determines its compression. See also borg recreate.
-

src/borg/archiver.py

@@ -1857,7 +1857,7 @@ class Archiver:
     helptext['patterns'] = textwrap.dedent('''
         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 experimental `--pattern`
+        ``--exclude`` patterns and shell-style is used for the experimental ``--pattern``
         option.
 
         If followed by a colon (':') the first two characters of a pattern are used as a
@@ -1866,8 +1866,7 @@ class Archiver:
         two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
 
         `Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`
-
-            This is the default style for --exclude and --exclude-from.
+            This is the default style for ``--exclude`` and ``--exclude-from``.
             These patterns use a variant of shell pattern syntax, with '\*' matching
             any number of characters, '?' matching any single character, '[...]'
             matching any single character specified, including ranges, and '[!...]'
@@ -1882,7 +1881,6 @@ class Archiver:
             separator, a '\*' is appended before matching is attempted.
 
         Shell-style patterns, selector `sh:`
-
             This is the default style for --pattern and --patterns-from.
             Like fnmatch patterns these are similar to shell patterns. The difference
             is that the pattern may include `**/` for matching zero or more directory
@@ -1890,7 +1888,6 @@ class Archiver:
             exception of any path separator.
 
         Regular expressions, selector `re:`
-
             Regular expressions similar to those found in Perl are supported. Unlike
             shell patterns regular expressions are not required to match the complete
             path and any substring match is sufficient. It is strongly recommended to
@@ -1901,12 +1898,10 @@ class Archiver:
             the re module <https://docs.python.org/3/library/re.html>`_.
 
         Path prefix, selector `pp:`
-
             This pattern style is useful to match whole sub-directories. The pattern
             `pp:/data/bar` matches `/data/bar` and everything therein.
 
         Path full-match, selector `pf:`
-
             This pattern style is useful to match whole paths.
             This is kind of a pseudo pattern as it can not have any variable or
             unspecified parts - the full, precise path must be given.
@@ -1930,11 +1925,11 @@ class Archiver:
             Further, ensure that `sh:` and `fm:` patterns only contain a handful of
             wildcards at most.
 
-        Exclusions can be passed via the command line option `--exclude`. When used
+        Exclusions can be passed via the command line option ``--exclude``. When used
         from within a shell the patterns should be quoted to protect them from
         expansion.
 
-        The `--exclude-from` option permits loading exclusion patterns from a text
+        The ``--exclude-from`` option permits loading exclusion patterns from a text
         file with one pattern per line. Lines empty or starting with the number sign
         ('#') after removing whitespace on both ends are ignored. The optional style
         selector prefix is also supported for patterns loaded from a file. Due to
@@ -1974,7 +1969,7 @@ class Archiver:
         .. container:: experimental
 
             A more general and easier to use way to define filename matching patterns exists
-            with the experimental `--pattern` and `--patterns-from` options. Using these, you
+            with the experimental ``--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
@@ -1983,15 +1978,15 @@ class Archiver:
             path. The first matching pattern is used so if an include pattern matches before
             an exclude pattern, the file is backed up.
 
-            Note that the default pattern style for `--pattern` and `--patterns-from` is
+            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.
+            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.
 
-            An example `--patterns-from` file could look like that::
+            An example ``--patterns-from`` file could look like that::
 
                 # "sh:" pattern style is the default, so the following line is not needed:
                 P sh
@@ -2006,49 +2001,39 @@ class Archiver:
                 # don't backup the other home directories
                 - /home/*\n\n''')
     helptext['placeholders'] = textwrap.dedent('''
-        Repository (or Archive) URLs, --prefix and --remote-path values support these
+        Repository (or Archive) URLs, ``--prefix`` and ``--remote-path`` values support these
         placeholders:
 
         {hostname}
-
             The (short) hostname of the machine.
 
         {fqdn}
-
             The full name of the machine.
 
         {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.4/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.4/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.
 
         {pid}
-
             The current process ID.
 
         {borgversion}
-
             The version of borg, e.g.: 1.0.8rc1
 
         {borgmajor}
-
             The version of borg, only the major version, e.g.: 1
 
         {borgminor}
-
             The version of borg, only major and minor version, e.g.: 1.0
 
         {borgpatch}
-
             The version of borg, only major, minor and patch version, e.g.: 1.0.8
 
         If literal curly braces need to be used, double them for escaping::
@@ -2071,20 +2056,26 @@ class Archiver:
             double all percent signs (``{hostname}-{now:%Y-%m-%d_%H:%M:%S}``
             becomes ``{hostname}-{now:%%Y-%%m-%%d_%%H:%%M:%%S}``).\n\n''')
     helptext['compression'] = textwrap.dedent('''
+        It is no problem to mix different compression methods in one repo,
+        deduplication is done on the source data chunks (not on the compressed
+        or encrypted data).
+
+        If some specific chunk was once compressed and stored into the repo, creating
+        another backup that also uses this chunk will not change the stored chunk.
+        So if you use different compression specs for the backups, whichever stores a
+        chunk first determines its compression. See also borg recreate.
+
         Compression is lz4 by default. If you want something else, you have to specify what you want.
 
         Valid compression specifiers are:
 
         none
-
             Do not compress.
 
         lz4
-
             Use lz4 compression. High speed, low compression. (default)
 
         zlib[,L]
-
             Use zlib ("gz") compression. Medium speed, medium compression.
             If you do not explicitely give the compression level L (ranging from 0
             to 9), it will use level 6.
@@ -2092,7 +2083,6 @@ class Archiver:
             overhead) is usually pointless, you better use "none" compression.
 
         lzma[,L]
-
             Use lzma ("xz") compression. Low speed, high compression.
             If you do not explicitely give the compression level L (ranging from 0
             to 9), it will use level 6.
@@ -2101,7 +2091,6 @@ class Archiver:
             lots of CPU cycles and RAM.
 
         auto,C[,L]
-
             Use a built-in heuristic to decide per chunk whether to compress or not.
             The heuristic tries with lz4 whether the data is compressible.
             For incompressible data, it will not use compression (uses "none").
@@ -2114,18 +2103,7 @@ class Archiver:
             borg create --compression zlib REPO::ARCHIVE data
             borg create --compression zlib,1 REPO::ARCHIVE data
             borg create --compression auto,lzma,6 REPO::ARCHIVE data
-            borg create --compression auto,lzma ...
-
-        General remarks:
-
-        It is no problem to mix different compression methods in one repo,
-        deduplication is done on the source data chunks (not on the compressed
-        or encrypted data).
-
-        If some specific chunk was once compressed and stored into the repo, creating
-        another backup that also uses this chunk will not change the stored chunk.
-        So if you use different compression specs for the backups, whichever stores a
-        chunk first determines its compression. See also borg recreate.\n\n''')
+            borg create --compression auto,lzma ...\n\n''')
 
     def do_help(self, parser, commands, args):
         if not args.topic: