build_man / build_usage

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

docs/man/borg-benchmark.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BENCHMARK" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-BENCHMARK" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .SH SYNOPSIS

docs/man/borg-break-lock.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BREAK-LOCK" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .SH SYNOPSIS

docs/man/borg-check.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-CHECK" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-CHECK" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .SH SYNOPSIS
@@ -35,94 +35,123 @@ borg-check \- Check repository consistency
 borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
 .SH DESCRIPTION
 .sp
-The check command verifies the consistency of a repository and the corresponding archives.
+The check command verifies the consistency of a repository and its archives.
+It consists of two major steps:
+.INDENT 0.0
+.IP 1. 3
+Checking the consistency of the repository itself. This includes checking
+the segment magic headers, and both the metadata and data of all objects in
+the segments. The read data is checked by size and CRC. Bit rot and other
+types of accidental damage can be detected this way. Running the repository
+check can be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
+When checking a remote repository, please note that the checks run on the
+server and do not cause significant network traffic.
+.IP 2. 3
+Checking consistency and correctness of the archive metadata and optionally
+archive data (requires \fB\-\-verify\-data\fP). This includes ensuring that the
+repository manifest exists, the archive metadata chunk is present, and that
+all chunks referencing files (items) in the archive exist. This requires
+reading archive and file metadata, but not data. To cryptographically verify
+the file (content) data integrity pass \fB\-\-verify\-data\fP, but keep in mind
+that this requires reading all data and is hence very time consuming. When
+checking archives of a remote repository, archive checks run on the client
+machine because they require decrypting data and therefore the encryption
+key.
+.UNINDENT
 .sp
-check \-\-repair is a potentially dangerous function and might lead to data loss
-(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL!
+Both steps can also be run independently. Pass \fB\-\-repository\-only\fP to run the
+repository checks only, or pass \fB\-\-archives\-only\fP to run the archive checks
+only.
 .sp
-Pursuant to the previous warning it is also highly recommended to test the
-reliability of the hardware running this software with stress testing software
-such as memory testers. Unreliable hardware can also lead to data loss especially
-when this command is run in repair mode.
+The \fB\-\-max\-duration\fP option can be used to split a long\-running repository
+check into multiple partial checks. After the given number of seconds the check
+is interrupted. The next partial check will continue where the previous one
+stopped, until the full repository has been checked. Assuming a complete check
+would take 7 hours, then running a daily check with \fB\-\-max\-duration=3600\fP
+(1 hour) would result in one full repository check per week. Doing a full
+repository check aborts any previous partial check; the next partial check will
+restart from the beginning. With partial repository checks you can run neither
+archive checks, nor enable repair mode. Consequently, if you want to use
+\fB\-\-max\-duration\fP you must also pass \fB\-\-repository\-only\fP, and must not pass
+\fB\-\-archives\-only\fP, nor \fB\-\-repair\fP\&.
+.sp
+\fBWarning:\fP Please note that partial repository checks (i.e. running it with
+\fB\-\-max\-duration\fP) can only perform non\-cryptographic checksum checks on the
+segment files. A full repository check (i.e. without \fB\-\-max\-duration\fP) can
+also do a repository index check. Enabling partial repository checks excepts
+archive checks for the same reason. Therefore partial checks may be useful with
+very large repositories only where a full check would take too long.
+.sp
+The \fB\-\-verify\-data\fP option will perform a full integrity verification (as
+opposed to checking the CRC32 of the segment) of data, which means reading the
+data from the repository, decrypting and decompressing it. It is a complete
+cryptographic verification and hence very time consuming, but will detect any
+accidental and malicious corruption. Tamper\-resistance is only guaranteed for
+encrypted repositories against attackers without access to the keys. You can
+not use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&.
+.SS About repair mode
+.sp
+The check command is a readonly task by default. If any corruption is found,
+Borg will report the issue and proceed with checking. To actually repair the
+issues found, pass \fB\-\-repair\fP\&.
 .sp
-First, the underlying repository data files are checked:
+\fBNOTE:\fP
 .INDENT 0.0
-.IP \(bu 2
-For all segments, the segment magic header is checked.
-.IP \(bu 2
-For all objects stored in the segments, all metadata (e.g. CRC and size) and
-all data is read. The read data is checked by size and CRC. Bit rot and other
-types of accidental damage can be detected this way.
-.IP \(bu 2
-In repair mode, if an integrity error is detected in a segment, try to recover
-as many objects from the segment as possible.
-.IP \(bu 2
-In repair mode, make sure that the index is consistent with the data stored in
-the segments.
-.IP \(bu 2
-If checking a remote repo via \fBssh:\fP, the repo check is executed on the server
-without causing significant network traffic.
-.IP \(bu 2
-The repository check can be skipped using the \fB\-\-archives\-only\fP option.
-.IP \(bu 2
-A repository check can be time consuming. Partial checks are possible with the
-\fB\-\-max\-duration\fP option.
+.INDENT 3.5
+\fB\-\-repair\fP is a \fBPOTENTIALLY DANGEROUS FEATURE\fP and might lead to data
+loss! This does not just include data that was previously lost anyway, but
+might include more data for kinds of corruption it is not capable of
+dealing with. \fBBE VERY CAREFUL!\fP
 .UNINDENT
+.UNINDENT
+.sp
+Pursuant to the previous warning it is also highly recommended to test the
+reliability of the hardware running Borg with stress testing software. This
+especially includes storage and memory testers. Unreliable hardware might lead
+to additional data loss.
 .sp
-Second, the consistency and correctness of the archive metadata is verified:
+It is highly recommended to create a backup of your repository before running
+in repair mode (i.e. running it with \fB\-\-repair\fP).
+.sp
+Repair mode will attempt to fix any corruptions found. Fixing corruptions does
+not mean recovering lost data: Borg can not magically restore data lost due to
+e.g. a hardware failure. Repairing a repository means sacrificing some data
+for the sake of the repository as a whole and the remaining data. Hence it is,
+by definition, a potentially lossy task.
+.sp
+In practice, repair mode hooks into both the repository and archive checks:
 .INDENT 0.0
-.IP \(bu 2
-Is the repo manifest present? If not, it is rebuilt from archive metadata
-chunks (this requires reading and decrypting of all metadata and data).
-.IP \(bu 2
-Check if archive metadata chunk is present; if not, remove archive from manifest.
-.IP \(bu 2
-For all files (items) in the archive, for all chunks referenced by these
-files, check if chunk is present. In repair mode, if a chunk is not present,
-replace it with a same\-size replacement chunk of zeroes. If a previously lost
-chunk reappears (e.g. via a later backup), in repair mode the all\-zero replacement
-chunk will be replaced by the correct chunk. This requires reading of archive and
-file metadata, but not data.
-.IP \(bu 2
-In repair mode, when all the archives were checked, orphaned chunks are deleted
-from the repo. One cause of orphaned chunks are input file related errors (like
-read errors) in the archive creation process.
-.IP \(bu 2
-In verify\-data mode, a complete cryptographic verification of the archive data
-integrity is performed. This conflicts with \fB\-\-repository\-only\fP as this mode
-only makes sense if the archive checks are enabled. The full details of this mode
-are documented below.
-.IP \(bu 2
-If checking a remote repo via \fBssh:\fP, the archive check is executed on the
-client machine because it requires decryption, and this is always done client\-side
-as key access is needed.
-.IP \(bu 2
-The archive checks can be time consuming; they can be skipped using the
-\fB\-\-repository\-only\fP option.
+.IP 1. 3
+When checking the repository\(aqs consistency, repair mode will try to recover
+as many objects from segments with integrity errors as possible, and ensure
+that the index is consistent with the data stored in the segments.
+.IP 2. 3
+When checking the consistency and correctness of archives, repair mode might
+remove whole archives from the manifest if their archive metadata chunk is
+corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
+will replace corrupt or lost chunks with a same\-size replacement chunk of
+zeroes. If a previously zeroed chunk reappears, repair mode will restore
+this lost chunk using the new chunk. Lastly, repair mode will also delete
+orphaned chunks (e.g. caused by read errors while creating the archive).
 .UNINDENT
 .sp
-The \fB\-\-max\-duration\fP option can be used to split a long\-running repository check
-into multiple partial checks. After the given number of seconds the check is
-interrupted. The next partial check will continue where the previous one stopped,
-until the complete repository has been checked. Example: Assuming a complete check took 7
-hours, then running a daily check with \-\-max\-duration=3600 (1 hour) resulted in one
-completed check per week.
-.sp
-Attention: A partial \-\-repository\-only check can only do way less checking than a full
-\-\-repository\-only check: only the non\-cryptographic checksum checks on segment file
-entries are done, while a full \-\-repository\-only check would also do a repo index check.
-A partial check cannot be combined with the \fB\-\-repair\fP option. Partial checks
-may therefore be useful only with very large repositories where a full check would take
-too long.
-Doing a full repository check aborts a partial check; the next partial check will restart
-from the beginning.
-.sp
-The \fB\-\-verify\-data\fP option will perform a full integrity verification (as opposed to
-checking the CRC32 of the segment) of data, which means reading the data from the
-repository, decrypting and decompressing it. This is a cryptographic verification,
-which will detect (accidental) corruption. For encrypted repositories it is
-tamper\-resistant as well, unless the attacker has access to the keys. It is also very
-slow.
+Most steps taken by repair mode have a one\-time effect on the repository, like
+removing a lost archive from the repository. However, replacing a corrupt or
+lost chunk with an all\-zero replacement will have an ongoing effect on the
+repository: When attempting to extract a file referencing an all\-zero chunk,
+the \fBextract\fP command will distinctly warn about it. The FUSE filesystem
+created by the \fBmount\fP command will reject reading such a \(dqzero\-patched\(dq
+file unless a special mount option is given.
+.sp
+As mentioned earlier, Borg might be able to \(dqheal\(dq a \(dqzero\-patched\(dq file in
+repair mode, if all its previously lost chunks reappear (e.g. via a later
+backup). This is achieved by Borg not only keeping track of the all\-zero
+replacement chunks, but also by keeping metadata about the lost chunks. In
+repair mode Borg will check whether a previously lost chunk reappeared and will
+replace the all\-zero replacement chunk by the reappeared chunk. If all lost
+chunks of a \(dqzero\-patched\(dq file reappear, this effectively \(dqheals\(dq the file.
+Consequently, if lost chunks were repaired earlier, it is advised to run
+\fB\-\-repair\fP a second time after creating some new backups.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

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 "2023-03-22" "" "borg backup tool"
+.TH "BORG-COMMON" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .SH SYNOPSIS

docs/man/borg-compact.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMPACT" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-COMPACT" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-compact \- compact segment files in the repository
 .SH SYNOPSIS

docs/man/borg-compression.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMPRESSION" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-COMPRESSION" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .SH DESCRIPTION
@@ -82,29 +82,70 @@ being any valid compression specifier.
 .TP
 .B obfuscate,SPEC,C[,L]
 Use compressed\-size obfuscation to make fingerprinting attacks based on
-the observable stored chunk size more difficult.
-Note:
-\- you must combine this with encryption or it won\(aqt make any sense.
-\- your repo size will be bigger, of course.
+the observable stored chunk size more difficult. Note:
+.INDENT 7.0
+.IP \(bu 2
+You must combine this with encryption, or it won\(aqt make any sense.
+.IP \(bu 2
+Your repo size will be bigger, of course.
+.IP \(bu 2
+A chunk is limited by the constant \fBMAX_DATA_SIZE\fP (cur. ~20MiB).
+.UNINDENT
+.sp
+The SPEC value determines how the size obfuscation works:
 .sp
-The SPEC value will determine how the size obfuscation will work:
+\fIRelative random reciprocal size variation\fP (multiplicative)
 .sp
-Relative random reciprocal size variation:
 Size will increase by a factor, relative to the compressed data size.
-Smaller factors are often used, larger factors rarely.
-1: factor 0.01 .. 100.0
-2: factor 0.1 .. 1000.0
-3: factor 1.0 .. 10000.0
-4: factor 10.0 .. 100000.0
-5: factor 100.0 .. 1000000.0
-6: factor 1000.0 .. 10000000.0
+Smaller factors are used often, larger factors rarely.
+.sp
+Available factors:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+1:     0.01 ..        100
+2:     0.1  ..      1,000
+3:     1    ..     10,000
+4:    10    ..    100,000
+5:   100    ..  1,000,000
+6: 1,000    .. 10,000,000
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Example probabilities for SPEC \fB1\fP:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+90   %  0.01 ..   0.1
+ 9   %  0.1  ..   1
+ 0.9 %  1    ..  10
+ 0.09% 10    .. 100
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fIRandomly sized padding up to the given size\fP (additive)
+.INDENT 7.0
+.INDENT 3.5
 .sp
-Add a randomly sized padding up to the given size:
-110: 1kiB
+.nf
+.ft C
+110: 1kiB (2 ^ (SPEC \- 100))
 \&...
 120: 1MiB
 \&...
 123: 8MiB (max.)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .UNINDENT
 .sp
 Examples:
@@ -120,7 +161,7 @@ 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 ...
-borg create \-\-compression obfuscate,3,none ...
+borg create \-\-compression obfuscate,110,none ...
 borg create \-\-compression obfuscate,3,auto,zstd,10 ...
 borg create \-\-compression obfuscate,2,zstd,6 ...
 .ft P

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

docs/man/borg-create.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-CREATE" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-CREATE" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .SH SYNOPSIS
@@ -169,15 +169,15 @@ set mode to M in archive for stdin data (default: 0660)
 interpret PATH as command and store its stdout. See also section Reading from stdin below.
 .TP
 .B  \-\-paths\-from\-stdin
-read DELIM\-separated list of paths to backup from stdin. Will not recurse into directories.
+read DELIM\-separated list of paths to backup from stdin. All control is external: it will back up all files given \- no more, no less.
 .TP
 .B  \-\-paths\-from\-command
 interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP
 .TP
 .BI \-\-paths\-delimiter \ DELIM
-set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: n)
+set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: \fB\en\fP)
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -208,7 +208,7 @@ exclude files flagged NODUMP
 .INDENT 0.0
 .TP
 .B  \-x\fP,\fB  \-\-one\-file\-system
-stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs.
+stay in the same file system and do not store mount points of other file systems \- this might behave different from your expectations, see the description below.
 .TP
 .B  \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
@@ -376,13 +376,13 @@ through using the \fB\-\-keep\-exclude\-tags\fP option.
 The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories, that are mountpoints (and everything in them).
 It detects mountpoints by comparing the device number from the output of \fBstat()\fP of the directory and its
 parent directory. Specifically, it excludes directories for which \fBstat()\fP reports a device number different
-from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
-with device number different from their parent, which the kernel does not consider a mountpoint and also the
-other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
-subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
-using \fB\-\-one\-file\-system\fP, one should make doubly sure that the backup works as intended especially when using
-btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
-installer.
+from the device number of their parent.
+In general: be aware that there are directories with device number different from their parent, which the kernel
+does not consider a mountpoint and also the other way around.
+Linux examples for this are bind mounts (possibly same device number, but always a mountpoint) and ALL
+subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint).
+macOS examples are the apfs mounts of a typical macOS installation.
+Therefore, when using \fB\-\-one\-file\-system\fP, you should double\-check that the backup works as intended.
 .SS Item flags
 .sp
 \fB\-\-list\fP outputs a list of all files, directories and other

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 "2023-03-22" "" "borg backup tool"
+.TH "BORG-DELETE" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .SH SYNOPSIS

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 "2023-03-22" "" "borg backup tool"
+.TH "BORG-DIFF" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .SH SYNOPSIS
@@ -87,7 +87,7 @@ Only compare differences in content (exclude metadata differences)
 .B  \-\-json\-lines
 Format output as JSON Lines.
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN

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 "2023-03-22" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS
@@ -100,7 +100,7 @@ filter program to pipe data through
 .B  \-\-list
 output verbose list of items (files, dirs, ...)
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN

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 "2023-03-22" "" "borg backup tool"
+.TH "BORG-EXTRACT" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .SH SYNOPSIS
@@ -105,7 +105,7 @@ write all extracted data to stdout
 .B  \-\-sparse
 create holes in output sparse file from all\-zero chunks
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN

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 "2023-03-22" "" "borg backup tool"
+.TH "BORG-IMPORT-TAR" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-import-tar \- Create a backup archive from a tarball
 .SH SYNOPSIS

docs/man/borg-info.1

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

docs/man/borg-init.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-INIT" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-INIT" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .SH SYNOPSIS
@@ -124,6 +124,8 @@ The key will be stored in your home directory (in \fB~/.config/borg/keys\fP).
 .sp
 If you do \fBnot\fP want to encrypt the contents of your backups, but still
 want to detect malicious tampering use \fB\-\-encryption authenticated\fP\&.
+To normally work with \fBauthenticated\fP repos, you will need the passphrase, but
+there is an emergency workaround, see \fBBORG_WORKAROUNDS=authenticated_no_key\fP docs.
 .sp
 If \fBBLAKE2b\fP is faster than \fBSHA\-256\fP on your hardware, use \fB\-\-encryption authenticated\-blake2\fP,
 \fB\-\-encryption repokey\-blake2\fP or \fB\-\-encryption keyfile\-blake2\fP\&. Note: for remote backups

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 "2023-03-22" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .SH SYNOPSIS

docs/man/borg-key-export.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-EXPORT" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .SH SYNOPSIS

docs/man/borg-key-import.1

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

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

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .SH SYNOPSIS

docs/man/borg-key.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-KEY" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-KEY" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-key \- Manage a keyfile or repokey of a repository
 .SH SYNOPSIS

docs/man/borg-list.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-LIST" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-LIST" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .SH SYNOPSIS
@@ -86,7 +86,7 @@ consider first N archives after other filters were applied
 .BI \-\-last \ N
 consider last N archives after other filters were applied
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
@@ -137,11 +137,11 @@ drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code/myproject
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
 \&...
 
-$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:\e.ext$\(aq
+$ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:\e.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
 \&...
 
-$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:.ext$\(aq
+$ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
 \&...

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 "2023-03-22" "" "borg backup tool"
+.TH "BORG-MOUNT" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -143,7 +143,7 @@ consider first N archives after other filters were applied
 .BI \-\-last \ N
 consider last N archives after other filters were applied
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN

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 "2023-03-22" "" "borg backup tool"
+.TH "BORG-PATTERNS" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
@@ -36,34 +36,20 @@ The path/filenames used as input for the pattern matching start from the
 currently active recursion root. You usually give the recursion root(s)
 when invoking borg and these can be either relative or absolute paths.
 .sp
-If you give \fI/absolute/\fP as root, the paths going into the matcher will
-look relative like \fIabsolute/.../file.ext\fP, because file paths in Borg
-archives are always stored normalized and relative. This means that e.g.
-\fBborg create /path/to/repo ../some/path\fP will 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\&.
+Starting with Borg 1.2, paths that are matched against patterns always
+appear relative. If you give \fB/absolute/\fP as root, the paths going
+into the matcher will start with \fBabsolute/\fP\&.
+If you give \fB\&../../relative\fP as root, the paths will be normalized
+as \fBrelative/\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
-option. For commands that support patterns in their \fBPATH\fP argument
-like (\fBborg list\fP), the default pattern is path prefix.
-.sp
-Starting with Borg 1.2, discovered fs paths are normalised, have leading
-slashes removed and then are matched against your patterns.
-Note: You need to review your include / exclude patterns and make
-sure they do not expect leading slashes. Borg can only deal with this
-for some very simple patterns by removing leading slashes there also.
-.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).
+Borg supports different pattern styles. To define a non\-default
+style for a specific pattern, prefix it with two characters followed
+by a colon \(aq:\(aq (i.e. \fBfm:path/*\fP, \fBsh:path/**\fP).
 .INDENT 0.0
 .TP
 .B \fI\%Fnmatch\fP, selector \fIfm:\fP
@@ -186,12 +172,37 @@ $ borg create \-\-exclude\-from exclude.txt backup /
 .UNINDENT
 .UNINDENT
 .sp
-A more general and easier to use way to define filename matching patterns exists
-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 \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.
+A more general and easier to use way to define filename matching patterns
+exists with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using
+these, you may specify the backup roots, default pattern styles and
+patterns for inclusion and exclusion.
+.INDENT 0.0
+.TP
+.B Root path prefix \fBR\fP
+A recursion root path starts with the prefix \fBR\fP, followed by a path
+(a plain path, not a file pattern). Use this prefix to have the root
+paths in the patterns file rather than as command line arguments.
+.TP
+.B Pattern style prefix \fBP\fP
+To change the default pattern style, use the \fBP\fP prefix, followed by
+the pattern style abbreviation (\fBfm\fP, \fBpf\fP, \fBpp\fP, \fBre\fP, \fBsh\fP).
+All patterns following this line will use this style until another style
+is specified.
+.TP
+.B Exclude pattern prefix \fB\-\fP
+Use the prefix \fB\-\fP, followed by a pattern, to define an exclusion.
+This has the same effect as the \fB\-\-exclude\fP option.
+.TP
+.B Exclude no\-recurse pattern prefix \fB!\fP
+Use the prefix \fB!\fP, followed by a pattern, to define an exclusion
+that does not recurse into subdirectories. This saves time, but
+prevents include patterns to match any files in subdirectories.
+.TP
+.B Include pattern prefix \fB+\fP
+Use the prefix \fB+\fP, followed by a pattern, to define inclusions.
+This is useful to include paths that are covered in an exclude
+pattern and would otherwise not be backed up.
+.UNINDENT
 .sp
 \fBNOTE:\fP
 .INDENT 0.0
@@ -202,11 +213,37 @@ of files using pattern prefixes \fB+\fP and \fB\-\fP\&. With \fB\-\-exclude\fP a
 .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.
+The first matching pattern is used, so if an include pattern matches
+before an exclude pattern, the file is backed up. Note that a no\-recurse
+exclude stops examination of subdirectories so that potential includes
+will not match \- use normal excludes for such use cases.
+.sp
+Example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Define the recursion root
+R /
+# Exclude all iso files in any directory
+\- **/*.iso
+# Explicitly include all inside etc and root
++ etc/**
++ root/**
+# Exclude a specific directory under each user\(aqs home directories
+\- home/*/.cache
+# Explicitly include everything in /home
++ home/**
+# Explicitly exclude some directories without recursing into them
+! re:^(dev|proc|run|sys|tmp)
+# Exclude all other files and directories
+# that are not specifically included earlier.
+\- **
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .sp
 \fBNOTE:\fP
 .INDENT 0.0

docs/man/borg-placeholders.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-PLACEHOLDERS" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-PLACEHOLDERS" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .SH DESCRIPTION

docs/man/borg-prune.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-PRUNE" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-PRUNE" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS

docs/man/borg-recreate.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-RECREATE" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-RECREATE" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .SH SYNOPSIS
@@ -112,7 +112,7 @@ do not change anything
 .B  \-s\fP,\fB  \-\-stats
 print statistics at end
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN

docs/man/borg-rename.1

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

docs/man/borg-serve.1

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

docs/man/borg-umount.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-UMOUNT" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-UMOUNT" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .SH SYNOPSIS

docs/man/borg-upgrade.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-UPGRADE" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-UPGRADE" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .SH SYNOPSIS

docs/man/borg-with-lock.1

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

docs/man/borg.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS
@@ -507,6 +507,38 @@ write to disk behaviour (not continuously streaming to disk).
 Retry opening a file without O_NOATIME if opening a file with O_NOATIME
 caused EROFS. You will need this to make archives from volume shadow copies
 in WSL1 (Windows Subsystem for Linux 1).
+.TP
+.B authenticated_no_key
+Work around a lost passphrase or key for an \fBauthenticated\fP mode repository
+(these are only authenticated, but not encrypted).
+If the key is missing in the repository config, add \fBkey = anything\fP there.
+.sp
+This workaround is \fBonly\fP for emergencies and \fBonly\fP to extract data
+from an affected repository (read\-only access):
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+After you have extracted all data you need, you MUST delete the repository:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+BORG_WORKAROUNDS=authenticated_no_key borg delete repo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now you can init a fresh repo. Make sure you do not use the workaround any more.
 .UNINDENT
 .UNINDENT
 .TP

docs/man/borgfs.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORGFS" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORGFS" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -146,7 +146,7 @@ consider first N archives after other filters were applied
 .BI \-\-last \ N
 consider last N archives after other filters were applied
 .UNINDENT
-.SS Exclusion options
+.SS Include/Exclude options
 .INDENT 0.0
 .TP
 .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN

docs/usage/check.rst.inc

@@ -85,75 +85,115 @@ borg check
 Description
 ~~~~~~~~~~~
 
-The check command verifies the consistency of a repository and the corresponding archives.
-
-check --repair is a potentially dangerous function and might lead to data loss
-(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL!
+The check command verifies the consistency of a repository and its archives.
+It consists of two major steps:
+
+1. Checking the consistency of the repository itself. This includes checking
+   the segment magic headers, and both the metadata and data of all objects in
+   the segments. The read data is checked by size and CRC. Bit rot and other
+   types of accidental damage can be detected this way. Running the repository
+   check can be split into multiple partial checks using ``--max-duration``.
+   When checking a remote repository, please note that the checks run on the
+   server and do not cause significant network traffic.
+
+2. Checking consistency and correctness of the archive metadata and optionally
+   archive data (requires ``--verify-data``). This includes ensuring that the
+   repository manifest exists, the archive metadata chunk is present, and that
+   all chunks referencing files (items) in the archive exist. This requires
+   reading archive and file metadata, but not data. To cryptographically verify
+   the file (content) data integrity pass ``--verify-data``, but keep in mind
+   that this requires reading all data and is hence very time consuming. When
+   checking archives of a remote repository, archive checks run on the client
+   machine because they require decrypting data and therefore the encryption
+   key.
+
+Both steps can also be run independently. Pass ``--repository-only`` to run the
+repository checks only, or pass ``--archives-only`` to run the archive checks
+only.
+
+The ``--max-duration`` option can be used to split a long-running repository
+check into multiple partial checks. After the given number of seconds the check
+is interrupted. The next partial check will continue where the previous one
+stopped, until the full repository has been checked. Assuming a complete check
+would take 7 hours, then running a daily check with ``--max-duration=3600``
+(1 hour) would result in one full repository check per week. Doing a full
+repository check aborts any previous partial check; the next partial check will
+restart from the beginning. With partial repository checks you can run neither
+archive checks, nor enable repair mode. Consequently, if you want to use
+``--max-duration`` you must also pass ``--repository-only``, and must not pass
+``--archives-only``, nor ``--repair``.
+
+**Warning:** Please note that partial repository checks (i.e. running it with
+``--max-duration``) can only perform non-cryptographic checksum checks on the
+segment files. A full repository check (i.e. without ``--max-duration``) can
+also do a repository index check. Enabling partial repository checks excepts
+archive checks for the same reason. Therefore partial checks may be useful with
+very large repositories only where a full check would take too long.
+
+The ``--verify-data`` 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. It is a complete
+cryptographic verification and hence very time consuming, but will detect any
+accidental and malicious corruption. Tamper-resistance is only guaranteed for
+encrypted repositories against attackers without access to the keys. You can
+not use ``--verify-data`` with ``--repository-only``.
+
+About repair mode
++++++++++++++++++
+
+The check command is a readonly task by default. If any corruption is found,
+Borg will report the issue and proceed with checking. To actually repair the
+issues found, pass ``--repair``.
+
+.. note::
+
+    ``--repair`` is a **POTENTIALLY DANGEROUS FEATURE** and might lead to data
+    loss! This does not just include data that was previously lost anyway, but
+    might include more data for kinds of corruption it is not capable of
+    dealing with. **BE VERY CAREFUL!**
 
 Pursuant to the previous warning it is also highly recommended to test the
-reliability of the hardware running this software with stress testing software
-such as memory testers. Unreliable hardware can also lead to data loss especially
-when this command is run in repair mode.
-
-First, the underlying repository data files are checked:
-
-- For all segments, the segment magic header is checked.
-- For all objects stored in the segments, all metadata (e.g. CRC and size) and
-  all data is read. The read data is checked by size and CRC. Bit rot and other
-  types of accidental damage can be detected this way.
-- In repair mode, if an integrity error is detected in a segment, try to recover
-  as many objects from the segment as possible.
-- In repair mode, make sure that the index is consistent with the data stored in
-  the segments.
-- If checking a remote repo via ``ssh:``, the repo check is executed on the server
-  without causing significant network traffic.
-- The repository check can be skipped using the ``--archives-only`` option.
-- A repository check can be time consuming. Partial checks are possible with the
-  ``--max-duration`` option.
-
-Second, the consistency and correctness of the archive metadata is verified:
-
-- Is the repo manifest present? If not, it is rebuilt from archive metadata
-  chunks (this requires reading and decrypting of all metadata and data).
-- Check if archive metadata chunk is present; if not, remove archive from manifest.
-- For all files (items) in the archive, for all chunks referenced by these
-  files, check if chunk is present. In repair mode, if a chunk is not present,
-  replace it with a same-size replacement chunk of zeroes. If a previously lost
-  chunk reappears (e.g. via a later backup), in repair mode the all-zero replacement
-  chunk will be replaced by the correct chunk. This requires reading of archive and
-  file metadata, but not data.
-- In repair mode, when all the archives were checked, orphaned chunks are deleted
-  from the repo. One cause of orphaned chunks are input file related errors (like
-  read errors) in the archive creation process.
-- In verify-data mode, a complete cryptographic verification of the archive data
-  integrity is performed. This conflicts with ``--repository-only`` as this mode
-  only makes sense if the archive checks are enabled. The full details of this mode
-  are documented below.
-- If checking a remote repo via ``ssh:``, the archive check is executed on the
-  client machine because it requires decryption, and this is always done client-side
-  as key access is needed.
-- The archive checks can be time consuming; they can be skipped using the
-  ``--repository-only`` option.
-
-The ``--max-duration`` option can be used to split a long-running repository check
-into multiple partial checks. After the given number of seconds the check is
-interrupted. The next partial check will continue where the previous one stopped,
-until the complete repository has been checked. Example: Assuming a complete check took 7
-hours, then running a daily check with --max-duration=3600 (1 hour) resulted in one
-completed check per week.
-
-Attention: A partial --repository-only check can only do way less checking than a full
---repository-only check: only the non-cryptographic checksum checks on segment file
-entries are done, while a full --repository-only check would also do a repo index check.
-A partial check cannot be combined with the ``--repair`` option. Partial checks
-may therefore be useful only with very large repositories where a full check would take
-too long.
-Doing a full repository check aborts a partial check; the next partial check will restart
-from the beginning.
-
-The ``--verify-data`` 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
-tamper-resistant as well, unless the attacker has access to the keys. It is also very
-slow.
+reliability of the hardware running Borg with stress testing software. This
+especially includes storage and memory testers. Unreliable hardware might lead
+to additional data loss.
+
+It is highly recommended to create a backup of your repository before running
+in repair mode (i.e. running it with ``--repair``).
+
+Repair mode will attempt to fix any corruptions found. Fixing corruptions does
+not mean recovering lost data: Borg can not magically restore data lost due to
+e.g. a hardware failure. Repairing a repository means sacrificing some data
+for the sake of the repository as a whole and the remaining data. Hence it is,
+by definition, a potentially lossy task.
+
+In practice, repair mode hooks into both the repository and archive checks:
+
+1. When checking the repository's consistency, repair mode will try to recover
+   as many objects from segments with integrity errors as possible, and ensure
+   that the index is consistent with the data stored in the segments.
+
+2. When checking the consistency and correctness of archives, repair mode might
+   remove whole archives from the manifest if their archive metadata chunk is
+   corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
+   will replace corrupt or lost chunks with a same-size replacement chunk of
+   zeroes. If a previously zeroed chunk reappears, repair mode will restore
+   this lost chunk using the new chunk. Lastly, repair mode will also delete
+   orphaned chunks (e.g. caused by read errors while creating the archive).
+
+Most steps taken by repair mode have a one-time effect on the repository, like
+removing a lost archive from the repository. However, replacing a corrupt or
+lost chunk with an all-zero replacement will have an ongoing effect on the
+repository: When attempting to extract a file referencing an all-zero chunk,
+the ``extract`` command will distinctly warn about it. The FUSE filesystem
+created by the ``mount`` command will reject reading such a "zero-patched"
+file unless a special mount option is given.
+
+As mentioned earlier, Borg might be able to "heal" a "zero-patched" file in
+repair mode, if all its previously lost chunks reappear (e.g. via a later
+backup). This is achieved by Borg not only keeping track of the all-zero
+replacement chunks, but also by keeping metadata about the lost chunks. In
+repair mode Borg will check whether a previously lost chunk reappeared and will
+replace the all-zero replacement chunk by the reappeared chunk. If all lost
+chunks of a "zero-patched" file reappear, this effectively "heals" the file.
+Consequently, if lost chunks were repaired earlier, it is advised to run
+``--repair`` a second time after creating some new backups.

docs/usage/create.rst.inc

@@ -12,107 +12,107 @@ borg create
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE``                                       | name of archive to create (must be also a valid directory name)                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``PATH``                                          | paths to archive                                                                                                                                     |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **options**                                                                                                                                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-n``, ``--dry-run``                             | do not create a backup archive                                                                                                                       |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-s``, ``--stats``                               | print statistics for the created archive                                                                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters (see description)                                                                                |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--json``                                        | output stats as JSON. Implies ``--stats``.                                                                                                           |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--no-cache-sync``                               | experimental: do not synchronize the cache. Implies not using the files cache.                                                                       |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-name NAME``                             | use NAME in archive for stdin data (default: 'stdin')                                                                                                |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-user USER``                             | set user USER in archive for stdin data (default: 'root')                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'wheel')                                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-mode M``                                | set mode to M in archive for stdin data (default: 0660)                                                                                              |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--content-from-command``                        | interpret PATH as command and store its stdout. See also section Reading from stdin below.                                                           |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--paths-from-stdin``                            | read DELIM-separated list of paths to backup from stdin. Will not recurse into directories.                                                          |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--paths-from-command``                          | interpret PATH as command and treat its output as ``--paths-from-stdin``                                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--paths-delimiter DELIM``                       | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n)                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                   |
-    |                                                                                                                                                                                                                                                                  |
-    | :ref:`common_options`                                                                                                                                                                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-e PATTERN``, ``--exclude PATTERN``             | exclude paths matching PATTERN                                                                                                                       |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                                 |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                             | include/exclude paths matching PATTERN                                                                                                               |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``                   | read include/exclude patterns from PATTERNFILE, one per line                                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--keep-exclude-tags``                           | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                            |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-nodump``                              | exclude files flagged NODUMP                                                                                                                         |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Filesystem options**                                                                                                                                                                                                                                           |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-x``, ``--one-file-system``                     | stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs. |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--numeric-owner``                               | deprecated, use ``--numeric-ids`` instead                                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--numeric-ids``                                 | only store numeric user and group identifiers                                                                                                        |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noatime``                                     | do not store atime into archive                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--atime``                                       | do store atime into archive                                                                                                                          |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noctime``                                     | do not store ctime into archive                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--nobirthtime``                                 | do not store birthtime (creation date) into archive                                                                                                  |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--nobsdflags``                                  | deprecated, use ``--noflags`` instead                                                                                                                |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noflags``                                     | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive                                                                                    |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noacls``                                      | do not read and store ACLs into archive                                                                                                              |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--noxattrs``                                    | do not read and store xattrs into archive                                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--sparse``                                      | detect sparse holes in input (supported only by fixed chunker)                                                                                       |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--files-cache MODE``                            | operate files cache in MODE. default: ctime,size,inode                                                                                               |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--read-special``                                | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.    |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive options**                                                                                                                                                                                                                                              |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                    |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--timestamp TIMESTAMP``                         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.                   |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                               |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095                |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                                     |
-    +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                                                                      |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``ARCHIVE``                                       | name of archive to create (must be also a valid directory name)                                                                                                   |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``PATH``                                          | paths to archive                                                                                                                                                  |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **options**                                                                                                                                                                                                                                                                   |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-n``, ``--dry-run``                             | do not create a backup archive                                                                                                                                    |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-s``, ``--stats``                               | print statistics for the created archive                                                                                                                          |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                                   |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters (see description)                                                                                             |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--json``                                        | output stats as JSON. Implies ``--stats``.                                                                                                                        |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--no-cache-sync``                               | experimental: do not synchronize the cache. Implies not using the files cache.                                                                                    |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--stdin-name NAME``                             | use NAME in archive for stdin data (default: 'stdin')                                                                                                             |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--stdin-user USER``                             | set user USER in archive for stdin data (default: 'root')                                                                                                         |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'wheel')                                                                                                      |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--stdin-mode M``                                | set mode to M in archive for stdin data (default: 0660)                                                                                                           |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--content-from-command``                        | interpret PATH as command and store its stdout. See also section Reading from stdin below.                                                                        |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--paths-from-stdin``                            | read DELIM-separated list of paths to backup from stdin. All control is external: it will back up all files given - no more, no less.                             |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--paths-from-command``                          | interpret PATH as command and treat its output as ``--paths-from-stdin``                                                                                          |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--paths-delimiter DELIM``                       | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``)                                                                      |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                |
+    |                                                                                                                                                                                                                                                                               |
+    | :ref:`common_options`                                                                                                                                                                                                                                                         |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **Include/Exclude options**                                                                                                                                                                                                                                                   |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-e PATTERN``, ``--exclude PATTERN``             | exclude paths matching PATTERN                                                                                                                                    |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                                              |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--pattern PATTERN``                             | include/exclude paths matching PATTERN                                                                                                                            |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--patterns-from PATTERNFILE``                   | read include/exclude patterns from PATTERNFILE, one per line                                                                                                      |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                                   |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                                         |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--keep-exclude-tags``                           | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                                         |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-nodump``                              | exclude files flagged NODUMP                                                                                                                                      |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **Filesystem options**                                                                                                                                                                                                                                                        |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-x``, ``--one-file-system``                     | stay in the same file system and do not store mount points of other file systems - this might behave different from your expectations, see the description below. |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--numeric-owner``                               | deprecated, use ``--numeric-ids`` instead                                                                                                                         |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--numeric-ids``                                 | only store numeric user and group identifiers                                                                                                                     |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--noatime``                                     | do not store atime into archive                                                                                                                                   |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--atime``                                       | do store atime into archive                                                                                                                                       |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--noctime``                                     | do not store ctime into archive                                                                                                                                   |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--nobirthtime``                                 | do not store birthtime (creation date) into archive                                                                                                               |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--nobsdflags``                                  | deprecated, use ``--noflags`` instead                                                                                                                             |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--noflags``                                     | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive                                                                                                 |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--noacls``                                      | do not read and store ACLs into archive                                                                                                                           |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--noxattrs``                                    | do not read and store xattrs into archive                                                                                                                         |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--sparse``                                      | detect sparse holes in input (supported only by fixed chunker)                                                                                                    |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--files-cache MODE``                            | operate files cache in MODE. default: ctime,size,inode                                                                                                            |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--read-special``                                | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.                 |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **Archive options**                                                                                                                                                                                                                                                           |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                                 |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--timestamp TIMESTAMP``                         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.                                |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                                            |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095                             |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                                                  |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -142,15 +142,15 @@ borg create
         --stdin-group GROUP    set group GROUP in archive for stdin data (default: 'wheel')
         --stdin-mode M    set mode to M in archive for stdin data (default: 0660)
         --content-from-command    interpret PATH as command and store its stdout. See also section Reading from stdin below.
-        --paths-from-stdin    read DELIM-separated list of paths to backup from stdin. Will not recurse into directories.
+        --paths-from-stdin    read DELIM-separated list of paths to backup from stdin. All control is external: it will back up all files given - no more, no less.
         --paths-from-command    interpret PATH as command and treat its output as ``--paths-from-stdin``
-        --paths-delimiter DELIM    set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n) 
+        --paths-delimiter DELIM    set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``)
 
 
     :ref:`common_options`
         |
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN
@@ -162,7 +162,7 @@ borg create
 
 
     Filesystem options
-        -x, --one-file-system     stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs.
+        -x, --one-file-system     stay in the same file system and do not store mount points of other file systems - this might behave different from your expectations, see the description below.
         --numeric-owner           deprecated, use ``--numeric-ids`` instead
         --numeric-ids             only store numeric user and group identifiers
         --noatime                 do not store atime into archive
@@ -282,13 +282,13 @@ through using the ``--keep-exclude-tags`` option.
 The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them).
 It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its
 parent directory. Specifically, it excludes directories for which ``stat()`` reports a device number different
-from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
-with device number different from their parent, which the kernel does not consider a mountpoint and also the
-other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
-subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
-using ``--one-file-system``, one should make doubly sure that the backup works as intended especially when using
-btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
-installer.
+from the device number of their parent.
+In general: be aware that there are directories with device number different from their parent, which the kernel
+does not consider a mountpoint and also the other way around.
+Linux examples for this are bind mounts (possibly same device number, but always a mountpoint) and ALL
+subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint).
+macOS examples are the apfs mounts of a typical macOS installation.
+Therefore, when using ``--one-file-system``, you should double-check that the backup works as intended.
 
 
 .. _list_item_flags:

docs/usage/diff.rst.inc

@@ -39,7 +39,7 @@ borg diff
     |                                                                                                                                                                       |
     | :ref:`common_options`                                                                                                                                                 |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                 |
+    | **Include/Exclude options**                                                                                                                                           |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                        |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
@@ -80,7 +80,7 @@ borg diff
     :ref:`common_options`
         |
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN

docs/usage/export-tar.rst.inc

@@ -31,7 +31,7 @@ borg export-tar
     |                                                                                                                                                                                                           |
     | :ref:`common_options`                                                                                                                                                                                     |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                     |
+    | **Include/Exclude options**                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                            |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -70,7 +70,7 @@ borg export-tar
     :ref:`common_options`
         |
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN

docs/usage/extract.rst.inc

@@ -45,7 +45,7 @@ borg extract
     |                                                                                                                                                                                                           |
     | :ref:`common_options`                                                                                                                                                                                     |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                     |
+    | **Include/Exclude options**                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                            |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -90,7 +90,7 @@ borg extract
     :ref:`common_options`
         |
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN

docs/usage/help.rst.inc

@@ -10,34 +10,20 @@ The path/filenames used as input for the pattern matching start from the
 currently active recursion root. You usually give the recursion root(s)
 when invoking borg and these can be either relative or absolute paths.
 
-If you give `/absolute/` as root, the paths going into the matcher will
-look relative like `absolute/.../file.ext`, because file paths in Borg
-archives are always stored normalized and relative. This means that e.g.
-``borg create /path/to/repo ../some/path`` will store all files as
-`some/path/.../file.ext` and ``borg create /path/to/repo /home/user``
-will store all files as `home/user/.../file.ext`.
+Starting with Borg 1.2, paths that are matched against patterns always
+appear relative. If you give ``/absolute/`` as root, the paths going
+into the matcher will start with ``absolute/``.
+If you give ``../../relative`` as root, the paths will be normalized
+as ``relative/``.
 
 A directory exclusion pattern can end either with or without a slash ('/').
 If it ends with a slash, such as `some/path/`, the directory will be
 included but not its content. If it does not end with a slash, such as
 `some/path`, both the directory and content will be excluded.
 
-File patterns support these styles: fnmatch, shell, regular expressions,
-path prefixes and path full-matches. By default, fnmatch is used for
-``--exclude`` patterns and shell-style is used for the ``--pattern``
-option. For commands that support patterns in their ``PATH`` argument
-like (``borg list``), the default pattern is path prefix.
-
-Starting with Borg 1.2, discovered fs paths are normalised, have leading
-slashes removed and then are matched against your patterns.
-Note: You need to review your include / exclude patterns and make
-sure they do not expect leading slashes. Borg can only deal with this
-for some very simple patterns by removing leading slashes there also.
-
-If followed by a colon (':') 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. `aa:something/*`).
+Borg supports different pattern styles. To define a non-default
+style for a specific pattern, prefix it with two characters followed
+by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``).
 
 `Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`
     This is the default style for ``--exclude`` and ``--exclude-from``.
@@ -147,12 +133,35 @@ Examples::
     EOF
     $ borg create --exclude-from exclude.txt backup /
 
-A more general and easier to use way to define filename matching patterns exists
-with the ``--pattern`` and ``--patterns-from`` options. Using these, you may
-specify the backup roots (starting points) and patterns for inclusion/exclusion.
-A root path starts with the prefix `R`, followed by a path (a plain path, not a
-file pattern). An include rule starts with the prefix +, an exclude rule starts
-with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
+A more general and easier to use way to define filename matching patterns
+exists with the ``--pattern`` and ``--patterns-from`` options. Using
+these, you may specify the backup roots, default pattern styles and
+patterns for inclusion and exclusion.
+
+Root path prefix ``R``
+    A recursion root path starts with the prefix ``R``, followed by a path
+    (a plain path, not a file pattern). Use this prefix to have the root
+    paths in the patterns file rather than as command line arguments.
+
+Pattern style prefix ``P``
+    To change the default pattern style, use the ``P`` prefix, followed by
+    the pattern style abbreviation (``fm``, ``pf``, ``pp``, ``re``, ``sh``).
+    All patterns following this line will use this style until another style
+    is specified.
+
+Exclude pattern prefix ``-``
+    Use the prefix ``-``, followed by a pattern, to define an exclusion.
+    This has the same effect as the ``--exclude`` option.
+
+Exclude no-recurse pattern prefix ``!``
+    Use the prefix ``!``, followed by a pattern, to define an exclusion
+    that does not recurse into subdirectories. This saves time, but
+    prevents include patterns to match any files in subdirectories.
+
+Include pattern prefix ``+``
+    Use the prefix ``+``, followed by a pattern, to define inclusions.
+    This is useful to include paths that are covered in an exclude
+    pattern and would otherwise not be backed up.
 
 .. note::
 
@@ -160,11 +169,29 @@ with the prefix -, an exclude-norecurse rule starts with !, all followed by a pa
     of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
     ``--exclude-from`` ONLY excludes are defined.
 
-Inclusion patterns are useful to include paths that are contained in an excluded
-path. The first matching pattern is used so if an include pattern matches before
-an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches
-a directory, it won't recurse into it and won't discover any potential matches for
-include rules below that directory.
+The first matching pattern is used, so if an include pattern matches
+before an exclude pattern, the file is backed up. Note that a no-recurse
+exclude stops examination of subdirectories so that potential includes
+will not match - use normal excludes for such use cases.
+
+Example::
+
+    # Define the recursion root
+    R /
+    # Exclude all iso files in any directory
+    - **/*.iso
+    # Explicitly include all inside etc and root
+    + etc/**
+    + root/**
+    # Exclude a specific directory under each user's home directories
+    - home/*/.cache
+    # Explicitly include everything in /home
+    + home/**
+    # Explicitly exclude some directories without recursing into them
+    ! re:^(dev|proc|run|sys|tmp)
+    # Exclude all other files and directories
+    # that are not specifically included earlier.
+    - **
 
 .. note::
 
@@ -346,29 +373,44 @@ auto,C[,L]
 
 obfuscate,SPEC,C[,L]
     Use compressed-size obfuscation to make fingerprinting attacks based on
-    the observable stored chunk size more difficult.
-    Note:
-    - you must combine this with encryption or it won't make any sense.
-    - your repo size will be bigger, of course.
+    the observable stored chunk size more difficult. Note:
+
+    - You must combine this with encryption, or it won't make any sense.
+    - Your repo size will be bigger, of course.
+    - A chunk is limited by the constant ``MAX_DATA_SIZE`` (cur. ~20MiB).
+
+    The SPEC value determines how the size obfuscation works:
 
-    The SPEC value will determine how the size obfuscation will work:
+    *Relative random reciprocal size variation* (multiplicative)
 
-    Relative random reciprocal size variation:
     Size will increase by a factor, relative to the compressed data size.
-    Smaller factors are often used, larger factors rarely.
-    1: factor 0.01 .. 100.0
-    2: factor 0.1 .. 1000.0
-    3: factor 1.0 .. 10000.0
-    4: factor 10.0 .. 100000.0
-    5: factor 100.0 .. 1000000.0
-    6: factor 1000.0 .. 10000000.0
-
-    Add a randomly sized padding up to the given size:
-    110: 1kiB
-    ...
-    120: 1MiB
-    ...
-    123: 8MiB (max.)
+    Smaller factors are used often, larger factors rarely.
+
+    Available factors::
+
+      1:     0.01 ..        100
+      2:     0.1  ..      1,000
+      3:     1    ..     10,000
+      4:    10    ..    100,000
+      5:   100    ..  1,000,000
+      6: 1,000    .. 10,000,000
+
+    Example probabilities for SPEC ``1``::
+
+      90   %  0.01 ..   0.1
+       9   %  0.1  ..   1
+       0.9 %  1    ..  10
+       0.09% 10    .. 100
+
+    *Randomly sized padding up to the given size* (additive)
+
+    ::
+
+      110: 1kiB (2 ^ (SPEC - 100))
+      ...
+      120: 1MiB
+      ...
+      123: 8MiB (max.)
 
 Examples::
 
@@ -379,7 +421,7 @@ Examples::
     borg create --compression zlib,1 REPO::ARCHIVE data
     borg create --compression auto,lzma,6 REPO::ARCHIVE data
     borg create --compression auto,lzma ...
-    borg create --compression obfuscate,3,none ...
+    borg create --compression obfuscate,110,none ...
     borg create --compression obfuscate,3,auto,zstd,10 ...
     borg create --compression obfuscate,2,zstd,6 ...
 

docs/usage/init.rst.inc

@@ -128,6 +128,8 @@ The key will be stored in your home directory (in ``~/.config/borg/keys``).
 
 If you do **not** want to encrypt the contents of your backups, but still
 want to detect malicious tampering use ``--encryption authenticated``.
+To normally work with ``authenticated`` repos, you will need the passphrase, but
+there is an emergency workaround, see ``BORG_WORKAROUNDS=authenticated_no_key`` docs.
 
 If ``BLAKE2b`` is faster than ``SHA-256`` on your hardware, use ``--encryption authenticated-blake2``,
 ``--encryption repokey-blake2`` or ``--encryption keyfile-blake2``. Note: for remote backups

docs/usage/list.rst.inc

@@ -47,7 +47,7 @@ borg list
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                                                                                                                                                                |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                                                                                                                                                                                          |
+    | **Include/Exclude options**                                                                                                                                                                                                                                                                                                                                                                    |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                                                                                                                                                                                           |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -93,7 +93,7 @@ borg list
         --last N                          consider last N archives after other filters were applied
 
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN

docs/usage/mount.rst.inc

@@ -49,7 +49,7 @@ borg mount
     +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                 |
     +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                           |
+    | **Include/Exclude options**                                                                                                                                                                                                     |
     +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                            |
     +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -99,7 +99,7 @@ borg mount
         --last N                          consider last N archives after other filters were applied
 
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN

docs/usage/prune.rst.inc

@@ -126,6 +126,12 @@ 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.
 
+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
+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.
+
 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,
 up to 7 most recent days with backups (days without backups do not count).
@@ -139,13 +145,6 @@ hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet
 its retention target. This enables the first chronological archive to continue
 aging until it is replaced by a newer archive that meets the retention criteria.
 
-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
-to keep all archives that were created within the past 48 hours.
-"1m" is taken to mean "31d". This option is applied before the secondly option
-and like the other options any archives kept by this option do not count towards
-the later rules.
-
 The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (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).
@@ -153,4 +152,4 @@ backup archive in the same second).
 When using ``--stats``, you will get some statistics about how much data was
 deleted - the "Deleted data" deduplicated size there is most interesting as
 that is how much your repository will shrink.
-Please note that the "All archives" stats refer to the state after pruning.
+Please note that the "All archives" stats refer to the state after pruning.

docs/usage/recreate.rst.inc

@@ -33,7 +33,7 @@ borg recreate
     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
     | :ref:`common_options`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+    | **Include/Exclude options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-e PATTERN``, ``--exclude PATTERN``             | exclude paths matching PATTERN                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -92,7 +92,7 @@ borg recreate
     :ref:`common_options`
         |
 
-    Exclusion options
+    Include/Exclude options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 include/exclude paths matching PATTERN