build_usage build_man

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CRUD" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .SH SYNOPSIS
@@ -37,7 +37,7 @@ borg [common options] benchmark crud [options] REPOSITORY PATH
 .sp
 This command benchmarks borg CRUD (create, read, update, delete) operations.
 .sp
-It creates input data below the given PATH and backups this data into the given REPO.
+It creates input data below the given PATH and backs up this data into the given REPO.
 The REPO must already exist (it could be a fresh empty repo or an existing repo, the
 command will create / read / update / delete some archives named borg\-benchmark\-crud* there.
 .sp
@@ -60,17 +60,17 @@ Also, due to the kind of content used, no compression is used in these benchmark
 .INDENT 0.0
 .TP
 .B C\- == borg create (1st archive creation, no compression, do not use files cache)
-C\-Z\- == all\-zero files. full dedup, this is primarily measuring reader/chunker/hasher.
-C\-R\- == random files. no dedup, measuring throughput through all processing stages.
+C\-Z\- == all\-zero files. full deduplication; this primarily measures reader/chunker/hasher.
+C\-R\- == random files. no deduplication, measuring throughput through all processing stages.
 .TP
 .B R\- == borg extract (extract archive, dry\-run, do everything, but do not write files to disk)
-R\-Z\- == all zero files. Measuring heavily duplicated files.
+R\-Z\- == all\-zero files. Measuring heavily duplicated files.
 R\-R\- == random files. No duplication here, measuring throughput through all processing
 stages, except writing to disk.
 .TP
 .B U\- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
 The throughput value is kind of virtual here, it does not actually read the file.
-U\-Z\- == needs to check the 2 all\-zero chunks\(aq existence in the repo.
+U\-Z\- == needs to check the two all\-zero chunks\(aq existence in the repo.
 U\-R\- == needs to check existence of a lot of different chunks in the repo.
 .TP
 .B D\- == borg delete archive (delete last remaining archive, measure deletion + compaction)
@@ -79,7 +79,7 @@ D\-R\- == many chunks to delete / many segments to compact/remove.
 .UNINDENT
 .sp
 Please note that there might be quite some variance in these measurements.
-Try multiple measurements and having a otherwise idle machine (and network, if you use it).
+Try multiple measurements and have an otherwise idle machine (and network, if you use it).
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -90,7 +90,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 repository to use for benchmark (must exist)
 .TP
 .B PATH
-path were to create benchmark input data
+path where to create benchmark input data
 .UNINDENT
 .SH SEE ALSO
 .sp

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-BENCHMARK" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .SH SYNOPSIS
@@ -37,7 +37,7 @@ borg [common options] benchmark crud ...
 .sp
 .SH DESCRIPTION
 .sp
-These commands do various benchmarks.
+These commands perform various benchmarks.
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-benchmark\-crud(1)\fP

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" "1" "2025-10-31" "" "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
@@ -36,8 +36,8 @@ borg [common options] break\-lock [options] [REPOSITORY]
 .SH DESCRIPTION
 .sp
 This command breaks the repository and cache locks.
-Please use carefully and only while no borg process (on any machine) is
-trying to access the Cache or the Repository.
+Please use with care and only when no borg process (on any machine) is
+trying to access the cache or the repository.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-CHECK" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .SH SYNOPSIS
@@ -78,7 +78,7 @@ archive checks, nor enable repair mode. Consequently, if you want to use
 \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
+also do a repository index check. Enabling partial repository checks excludes
 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
@@ -87,11 +87,11 @@ 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\&.
+encrypted repositories against attackers without access to the keys. You cannot
+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,
+The check command is a read\-only 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

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-COMMON" "1" "2025-10-31" "" "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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-COMPACT" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-compact \- compact segment files in the repository
 .SH SYNOPSIS
@@ -51,8 +51,15 @@ A segment is compacted if the amount of saved space is above the percentage valu
 given by the \fB\-\-threshold\fP option. If omitted, a threshold of 10% is used.
 When using \fB\-\-verbose\fP, borg will output an estimate of the freed space.
 .sp
+For maximum compaction, use \fB\-\-threshold 0\fP\&. This will compact whenever any
+space can be saved and thus rewrites the most data; it can be much slower on
+large repositories. Using \fB\-\-threshold 1\fP usually achieves nearly the same
+result significantly faster. Higher thresholds (e.g. the default 10) trade
+compaction thoroughness for speed. Note: \fB\-\-threshold 100\fP will effectively
+compact nothing.
+.sp
 After upgrading borg (server) to 1.2+, you can use \fBborg compact \-\-cleanup\-commits\fP
-to clean up the numerous 17byte commit\-only segments that borg 1.1 did not clean up
+to clean up the numerous 17\-byte commit\-only segments that borg 1.1 did not clean up
 due to a bug. It is enough to do that once per repository. After cleaning up the
 commits, borg will also do a normal compaction.
 .sp
@@ -86,7 +93,7 @@ set minimum threshold for saved space in PERCENT (Default: 10)
 # compact segments and free repo disk space
 $ borg compact /path/to/repo
 
-# same as above plus clean up 17byte commit\-only segments
+# same as above plus clean up 17\-byte commit\-only segments
 $ borg compact \-\-cleanup\-commits /path/to/repo
 .EE
 .UNINDENT

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-COMPRESSION" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .SH DESCRIPTION

docs/man/borg-config.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-CONFIG" "1" "2025-04-18" "" "borg backup tool"
+.TH "BORG-CONFIG" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-config \- get, set, and delete values in a repository or cache config file
 .SH SYNOPSIS
@@ -39,7 +39,7 @@ This command gets and sets options in a local repository or cache config file.
 For security reasons, this command only works on local repositories.
 .sp
 To delete a config value entirely, use \fB\-\-delete\fP\&. To list the values
-of the configuration file or the default values, use \fB\-\-list\fP\&.  To get an existing
+of the configuration file or the default values, use \fB\-\-list\fP\&. To get an existing
 key, pass only the key name. To set a key, pass both the key name and
 the new value. Keys can be specified in the format \(dqsection.name\(dq or
 simply \(dqname\(dq; the section will default to \(dqrepository\(dq and \(dqcache\(dq for

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-CREATE" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .SH SYNOPSIS
@@ -37,18 +37,18 @@ borg [common options] create [options] ARCHIVE [PATH...]
 .sp
 This command creates a backup archive containing all files found while recursively
 traversing all paths specified. Paths are added to the archive as they are given,
-that means if relative paths are desired, the command has to be run from the correct
+which means that if relative paths are desired, the command has to be run from the correct
 directory.
 .sp
 The slashdot hack in paths (recursion roots) is triggered by using \fB/./\fP:
-\fB/this/gets/stripped/./this/gets/archived\fP means to process that fs object, but
+\fB/this/gets/stripped/./this/gets/archived\fP means to process that filesystem object, but
 strip the prefix on the left side of \fB\&./\fP from the archived items (in this case,
 \fBthis/gets/archived\fP will be the path in the archived item).
 .sp
-When giving \(aq\-\(aq as path, borg will read data from standard input and create a
-file \(aqstdin\(aq in the created archive from that data. In some cases it\(aqs more
-appropriate to use \-\-content\-from\-command, however. See section \fIReading from
-stdin\fP below for details.
+When giving \(aq\-\(aq as a path, Borg will read data from standard input and create a
+file \(aqstdin\(aq in the created archive from that data. In some cases, it is more
+appropriate to use \fB\-\-content\-from\-command\fP\&. See section \(dqReading from stdin\(dq
+below for details.
 .sp
 The archive will consume almost no disk space for files or parts of files that
 have already been stored in other archives.
@@ -70,7 +70,7 @@ This comparison can operate in different modes as given by \fB\-\-files\-cache\f
 .IP \(bu 2
 ctime,size,inode (default)
 .IP \(bu 2
-mtime,size,inode (default behaviour of borg versions older than 1.1.0rc4)
+mtime,size,inode (default behavior of borg versions older than 1.1.0rc4)
 .IP \(bu 2
 ctime,size (ignore the inode number)
 .IP \(bu 2
@@ -83,37 +83,49 @@ rechunk,mtime (all files are considered modified \- rechunk, cache mtime)
 disabled (disable the files cache, all files considered modified \- rechunk)
 .UNINDENT
 .sp
-inode number: better safety, but often unstable on network filesystems
+inode number: better safety, but often unstable on network file systems
 .sp
 Normally, detecting file modifications will take inode information into
 consideration to improve the reliability of file change detection.
-This is problematic for files located on sshfs and similar network file
-systems which do not provide stable inode numbers, such files will always
+This is problematic for files located on SSHFS and similar network file
+systems which do not provide stable inode numbers; such files will always
 be considered modified. You can use modes without \fIinode\fP in this case to
-improve performance, but reliability of change detection might be reduced.
+improve performance, but the reliability of change detection might be reduced.
 .sp
 ctime vs. mtime: safety vs. speed
 .INDENT 0.0
 .IP \(bu 2
 ctime is a rather safe way to detect changes to a file (metadata and contents)
-as it can not be set from userspace. But, a metadata\-only change will already
+as it cannot be set from user space. However, a metadata\-only change will already
 update the ctime, so there might be some unnecessary chunking/hashing even
-without content changes. Some filesystems do not support ctime (change time).
-E.g. doing a chown or chmod to a file will change its ctime.
+without content changes. Some file systems do not support ctime (change time).
+For example, doing a chown or chmod to a file will change its ctime.
 .IP \(bu 2
 mtime usually works and only updates if file contents were changed. But mtime
-can be arbitrarily set from userspace, e.g. to set mtime back to the same value
+can be arbitrarily set from user space, e.g., to set mtime back to the same value
 it had before a content change happened. This can be used maliciously as well as
-well\-meant, but in both cases mtime based cache modes can be problematic.
+well\-meant, but in both cases mtime\-based cache modes can be problematic.
 .UNINDENT
 .sp
-The mount points of filesystems or filesystem snapshots should be the same for every
+The \fB\-\-files\-changed\fP option controls how Borg detects if a file has changed during backup:
+.INDENT 0.0
+.IP \(bu 2
+ctime (default): Use ctime to detect changes. This is the safest option.
+.IP \(bu 2
+mtime: Use mtime to detect changes.
+.IP \(bu 2
+disabled: Disable the \(dqfile has changed while we backed it up\(dq detection completely.
+This is not recommended unless you know what you\(aqre doing, as it could lead to
+inconsistent backups if files change during the backup process.
+.UNINDENT
+.sp
+The mount points of file systems or file system snapshots should be the same for every
 creation of a new archive to ensure fast operation. This is because the file cache that
-is used to determine changed files quickly uses absolute filenames.
+is used to determine changed files quickly uses absolute file names.
 If this is not possible, consider creating a bind mount to a stable location.
 .sp
 The \fB\-\-progress\fP option shows (from left to right) Original, Compressed and Deduplicated
-(O, C and D, respectively), then the Number of files (N) processed so far, followed by
+(O, C and D, respectively), then the number of files (N) processed so far, followed by
 the currently processed path.
 .sp
 When using \fB\-\-stats\fP, you will get some statistics about how much data was
@@ -251,6 +263,9 @@ detect sparse holes in input (supported only by fixed chunker)
 .BI \-\-files\-cache \ MODE
 operate files cache in MODE. default: ctime,size,inode
 .TP
+.BI \-\-files\-changed \ MODE
+specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime
+.TP
 .B  \-\-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.
 .UNINDENT
@@ -379,15 +394,15 @@ only include the objects specified by \fB\-\-exclude\-if\-present\fP in your bac
 and not include any other contents of the containing folder, this can be enabled
 through using the \fB\-\-keep\-exclude\-tags\fP option.
 .sp
-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
+The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories that are mount points (and everything in them).
+It detects mount points 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.
-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.
+In general: be aware that there are directories with device numbers different from their parent, which the kernel
+does not consider mount points, and vice versa.
+Linux examples for this are bind mounts (possibly same device number, but always a mount point) and all
+subvolumes of a Btrfs file system (different device numbers from the parent but not necessarily mount points).
+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

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-DELETE" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .SH SYNOPSIS
@@ -132,7 +132,7 @@ $ borg delete \-\-glob\-archives \(aq{hostname}\-*\(aq /path/to/repo
 # delete all archives whose names contain \(dq\-2012\-\(dq
 $ borg delete \-\-glob\-archives \(aq*\-2012\-*\(aq /path/to/repo
 
-# see what would be deleted if delete was run without \-\-dry\-run
+# see what would be deleted if delete were run without \-\-dry\-run
 $ borg delete \-\-list \-\-dry\-run \-a \(aq*\-May\-*\(aq /path/to/repo
 
 # delete the whole repository and the related local cache:

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-DIFF" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .SH SYNOPSIS
@@ -38,17 +38,84 @@ borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
 This command finds differences (file contents, user/group/mode) between archives.
 .sp
 A repository location and an archive name must be specified for REPO::ARCHIVE1.
-ARCHIVE2 is just another archive name in same repository (no repository location
+ARCHIVE2 is just another archive name in the same repository (no repository location
 allowed).
+.SS What is compared
 .sp
-For archives created with Borg 1.1 or newer diff automatically detects whether
-the archives are created with the same chunker params. If so, only chunk IDs
+For each matching item in both archives, Borg reports:
+.INDENT 0.0
+.IP \(bu 2
+Content changes: total added/removed bytes within files. If chunker parameters are comparable,
+Borg compares chunk IDs quickly; otherwise, it compares the content.
+.IP \(bu 2
+Metadata changes: user, group, mode, and other metadata shown inline like
+\(dq[old_mode \-> new_mode]\(dq for mode changes. Use \fB\-\-content\-only\fP to suppress metadata changes.
+.IP \(bu 2
+Added/removed items: printed as \(dqadded SIZE path\(dq or \(dqremoved SIZE path\(dq.
+.UNINDENT
+.SS Output formats
+.sp
+The default (text) output shows one line per changed path, e.g.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
++135 B    \-252 B [ \-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x ] path/to/file
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+JSON Lines output (\fB\-\-json\-lines\fP) prints one JSON object per changed path, e.g.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+{\(dqpath\(dq: \(dqPATH\(dq, \(dqchanges\(dq: [
+    {\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: BYTES, \(dqremoved\(dq: BYTES},
+    {\(dqtype\(dq: \(dqmode\(dq, \(dqold_mode\(dq: \(dq\-rw\-r\-\-r\-\-\(dq, \(dqnew_mode\(dq: \(dq\-rwxr\-xr\-x\(dq},
+    {\(dqtype\(dq: \(dqadded\(dq, \(dqsize\(dq: SIZE},
+    {\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: SIZE}
+]}
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+Only actual changes are included in the \(dqchanges\(dq list. For example, a modified entry with
+added=0 and removed=0 is omitted.
+.SS Sorting
+.sp
+Use \fB\-\-sort\-by FIELDS\fP where FIELDS is a comma\-separated list of fields.
+Sorts are applied stably from last to first in the given list. Prepend \(dq>\(dq for
+descending, \(dq<\(dq (or no prefix) for ascending, for example \fB\-\-sort\-by=\(dq>size_added,path\(dq\fP\&.
+Supported fields include:
+.INDENT 0.0
+.IP \(bu 2
+path: the item path
+.IP \(bu 2
+size_added: total bytes added for the item content
+.IP \(bu 2
+size_removed: total bytes removed for the item content
+.IP \(bu 2
+size_diff: size_added \- size_removed (net content change)
+.IP \(bu 2
+size: size of the item as stored in ARCHIVE2 (0 for removed items)
+.IP \(bu 2
+user, group, uid, gid, ctime, mtime: taken from the item state in ARCHIVE2 when present
+.IP \(bu 2
+ctime_diff, mtime_diff: timestamp difference (archive2 \- archive1)
+.UNINDENT
+.sp
+The \fB\-\-sort\fP option is deprecated and only sorts by path.
+.SS Performance considerations
+.sp
+For archives created with Borg 1.1 or newer, diff automatically detects whether
+the archives were created with the same chunker parameters. If so, only chunk IDs
 are compared, which is very fast.
 .sp
-For archives prior to Borg 1.1 chunk contents are compared by default.
-If you did not create the archives with different chunker params,
+For archives prior to Borg 1.1, chunk contents are compared by default.
+If you did not create the archives with different chunker parameters,
 pass \fB\-\-same\-chunker\-params\fP\&.
-Note that the chunker params changed from Borg 0.xx to 1.0.
+Note that the chunker parameters changed from Borg 0.xx to 1.0.
 .sp
 For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
 .SH OPTIONS
@@ -79,14 +146,14 @@ only consider numeric user and group identifiers
 Override check of chunker parameters.
 .TP
 .B  \-\-sort
-Sort the output lines by file path.
-.TP
-.B  \-\-content\-only
-Only compare differences in content (exclude metadata differences)
-.TP
-.B  \-\-json\-lines
-Format output as JSON Lines.
+Sort the output by path (deprecated, use \-\-sort\-by=path).
 .UNINDENT
+.IP "System Message: WARNING/2 (docs/borg-diff.rst:, line 119)"
+Option list ends without a blank line; unexpected unindent.
+.sp
+\-\-sort\-by FIELD[,FIELD...]      Advanced sorting: specify field(s) to sort by. Accepts a comma\-separated list. Prefix with > for descending or < for ascending (default).
+\-\-content\-only                  Only compare differences in content (exclude metadata differences)
+\-\-json\-lines                    Format output as JSON Lines.
 .SS Include/Exclude options
 .INDENT 0.0
 .TP
@@ -144,7 +211,15 @@ $ borg diff \-\-json\-lines testrepo::archive1 archive3
 {\(dqpath\(dq: \(dqfile1\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: 17, \(dqremoved\(dq: 5}, {\(dqtype\(dq: \(dqmode\(dq, \(dqold_mode\(dq: \(dq\-rw\-r\-\-r\-\-\(dq, \(dqnew_mode\(dq: \(dq\-rwxr\-xr\-x\(dq}]}
 {\(dqpath\(dq: \(dqfile2\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: 135, \(dqremoved\(dq: 252}]}
 {\(dqpath\(dq: \(dqfile4\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqadded\(dq, \(dqsize\(dq: 0}]}
-{\(dqpath\(dq: \(dqfile3\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: 0}]
+{\(dqpath\(dq: \(dqfile3\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: 0}]}
+
+# Use \-\-sort\-by with a comma\-separated list; sorts apply stably from last to first.
+# Here: primary by net size change descending, tie\-breaker by path ascending
+$ borg diff \-\-sort\-by=\(dq>size_diff,path\(dq testrepo::archive1 archive3
+    +17 B      \-5 B [\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
+removed         0 B file3
+added           0 B file4
+   +135 B    \-252 B file2
 .EE
 .UNINDENT
 .UNINDENT

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS
@@ -66,7 +66,7 @@ BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported.
 Timestamp resolution is limited to whole seconds, not the nanosecond resolution
 otherwise supported by Borg.
 .sp
-A \fB\-\-sparse\fP option (as found in borg extract) is not supported.
+A \fB\-\-sparse\fP option (as found in \fBborg extract\fP) is not supported.
 .sp
 By default the entire archive is extracted but a subset of files and directories
 can be selected by passing a list of \fBPATHs\fP as arguments.
@@ -123,20 +123,20 @@ Remove the specified number of leading path elements. Paths with fewer elements
 .INDENT 3.5
 .sp
 .EX
-# export as uncompressed tar
+# Export as an uncompressed tar.
 $ borg export\-tar /path/to/repo::Monday Monday.tar
 
-# exclude some types, compress using gzip
+# Exclude some types; compress using gzip.
 $ borg export\-tar /path/to/repo::Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq
 
-# use higher compression level with gzip
+# Use a higher compression level with gzip.
 $ borg export\-tar \-\-tar\-filter=\(dqgzip \-9\(dq testrepo::linux Monday.tar.gz
 
-# export a tar, but instead of storing it on disk,
+# Export a tar, but instead of storing it on disk,
 # upload it to a remote site using curl.
 $ borg export\-tar /path/to/repo::Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST
 
-# remote extraction via \(dqtarpipe\(dq
+# Remote extraction via \(dqtarpipe\(dq.
 $ borg export\-tar /path/to/repo::Monday \- | ssh somewhere \(dqcd extracted; tar x\(dq
 .EE
 .UNINDENT

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-EXTRACT" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .SH SYNOPSIS
@@ -35,16 +35,20 @@ borg-extract \- Extract archive contents
 borg [common options] extract [options] ARCHIVE [PATH...]
 .SH DESCRIPTION
 .sp
-This command extracts the contents of an archive. By default the entire
-archive is extracted but a subset of files and directories can be selected
-by passing a list of \fBPATHs\fP as arguments. The file selection can further
-be restricted by using the \fB\-\-exclude\fP option.
+This command extracts the contents of an archive.
 .sp
+By default, the entire archive is extracted, but a subset of files and directories
+can be selected by passing a list of \fBPATH\fP arguments. The default interpretation
+for the paths to extract is \fIpp:\fP which is a literal path\-prefix match. If you want
+to use e.g. a wildcard, you must select a different pattern style such as \fIsh:\fP or
+\fIfm:\fP\&. See \fIborg_patterns\fP for more information.
+.sp
+The file selection can be further restricted by using the \fB\-\-exclude\fP option.
 For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
 .sp
 By using \fB\-\-dry\-run\fP, you can do all extraction steps except actually writing the
-output data: reading metadata and data chunks from the repo, checking the hash/hmac,
-decrypting, decompressing.
+output data: reading metadata and data chunks from the repository, checking the hash/HMAC,
+decrypting, and decompressing.
 .sp
 \fB\-\-progress\fP can be slower than no progress display, since it makes one additional
 pass over the archive metadata.
@@ -56,8 +60,8 @@ Currently, extract always writes into the current working directory (\(dq.\(dq),
 so make sure you \fBcd\fP to the right place before calling \fBborg extract\fP\&.
 .sp
 When parent directories are not extracted (because of using file/directory selection
-or any other reason), borg can not restore parent directories\(aq metadata, e.g. owner,
-group, permission, etc.
+or any other reason), Borg cannot restore parent directories\(aq metadata, e.g., owner,
+group, permissions, etc.
 .UNINDENT
 .UNINDENT
 .SH OPTIONS
@@ -143,6 +147,9 @@ $ borg extract /path/to/repo::my\-files home/USERNAME/src
 # Extract the \(dqsrc\(dq directory but exclude object files
 $ borg extract /path/to/repo::my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq
 
+# Extract only the C files
+$ borg extract /path/to/repo::my\-files \(aqsh:home/USERNAME/src/*.c\(aq
+
 # Restore a raw device (must not be active/in use/mounted at that time)
 $ borg extract \-\-stdout /path/to/repo::my\-sdx | dd of=/dev/sdx bs=10M
 .EE

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-IMPORT-TAR" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-import-tar \- Create a backup archive from a tarball
 .SH SYNOPSIS
@@ -37,9 +37,9 @@ borg [common options] import\-tar [options] ARCHIVE TARFILE
 .sp
 This command creates a backup archive from a tarball.
 .sp
-When giving \(aq\-\(aq as path, Borg will read a tar stream from standard input.
+When giving \(aq\-\(aq as a path, Borg will read a tar stream from standard input.
 .sp
-By default (\-\-tar\-filter=auto) Borg will detect whether the file is compressed
+By default (\fB\-\-tar\-filter=auto\fP) Borg will detect whether the file is compressed
 based on its file extension and pipe the file through an appropriate filter:
 .INDENT 0.0
 .IP \(bu 2
@@ -54,11 +54,11 @@ based on its file extension and pipe the file through an appropriate filter:
 \&.tar.lz4: lz4 \-d
 .UNINDENT
 .sp
-Alternatively, a \-\-tar\-filter program may be explicitly specified. It should
+Alternatively, a \fB\-\-tar\-filter\fP program may be explicitly specified. It should
 read compressed data from stdin and output an uncompressed tar stream on
 stdout.
 .sp
-Most documentation of borg create applies. Note that this command does not
+Most documentation of \fBborg create\fP applies. Note that this command does not
 support excluding files.
 .sp
 import\-tar is a lossy conversion:

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-INFO" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS
@@ -39,11 +39,11 @@ This command displays detailed information about the specified archive or reposi
 .sp
 Please note that the deduplicated sizes of the individual archives do not add
 up to the deduplicated size of the repository (\(dqall archives\(dq), because the two
-are meaning different things:
+mean different things:
 .sp
 This archive / deduplicated size = amount of data stored ONLY for this archive
 = unique chunks of this archive.
-All archives / deduplicated size = amount of data stored in the repo
+All archives / deduplicated size = amount of data stored in the repository
 = all chunks in the repository.
 .sp
 Borg archives can only contain a limited amount of file metadata.

docs/man/borg-init.1

@@ -28,7 +28,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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-INIT" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .SH SYNOPSIS
@@ -36,97 +36,115 @@ borg-init \- Initialize an empty repository
 borg [common options] init [options] [REPOSITORY]
 .SH DESCRIPTION
 .sp
-This command initializes an empty repository. A repository is a filesystem
-directory containing the deduplicated data from zero or more archives.
-.SS Encryption mode TLDR
+This command initializes an empty repository. A repository is a
+filesystem directory containing the deduplicated data from zero or more
+archives.
+.SS Encryption mode TL;DR
 .sp
-The encryption mode can only be configured when creating a new repository \-
-you can neither configure it on a per\-archive basis nor change the
-encryption mode of an existing repository.
+The encryption mode can only be configured when creating a new
+repository. You can neither configure encryption on a per\-archive
+basis, nor change the encryption mode of an existing repository. You
+should thus take possible future use into account when deciding on an
+encryption mode.
 .sp
-Use \fBrepokey\fP:
+As a general rule of thumb, use \fBrepokey\fP with a strong passphrase:
 .INDENT 0.0
 .INDENT 3.5
-.sp
-.EX
 borg init \-\-encryption repokey /path/to/repo
-.EE
 .UNINDENT
 .UNINDENT
 .sp
-Or \fBrepokey\-blake2\fP depending on which is faster on your client machines (see below):
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.EX
-borg init \-\-encryption repokey\-blake2 /path/to/repo
-.EE
-.UNINDENT
-.UNINDENT
-.sp
-Borg will:
+However, there are many reasons to choose differently. See the section
+below for details. In any case, Borg will:
 .INDENT 0.0
 .IP 1. 3
-Ask you to come up with a passphrase.
+Ask you to enter a unique and strong passphrase.
 .IP 2. 3
-Create a borg key (which contains 3 random secrets. See \fIkey_files\fP).
+Create a random Borg key (which actually consists of three random
+secrets, see \fIkey_files\fP for details).
 .IP 3. 3
-Encrypt the key with your passphrase.
+Encrypt the Borg key with your passphrase.
 .IP 4. 3
-Store the encrypted borg key inside the repository directory (in the repo config).
-This is why it is essential to use a secure passphrase.
+Store the encrypted Borg key inside the repository directory (with
+\fBrepokey\fP and \fBrepokey\-blake2\fP modes; with \fBkeyfile\fP and
+\fBkeyfile\-blake2\fP modes the Borg key is stored in your home
+directory instead, see below). Since we usually have to assume that
+an attacker could gain access to the repository (that\(aqs why we
+encrypt the data in the first place), choosing a strong and unique
+passphrase is absolutely crucial.
 .IP 5. 3
-Encrypt and sign your backups to prevent anyone from reading or forging them unless they
-have the key and know the passphrase. Make sure to keep a backup of
-your key \fBoutside\fP the repository \- do not lock yourself out by
-\(dqleaving your keys inside your car\(dq (see \fIborg_key_export\fP).
-For remote backups the encryption is done locally \- the remote machine
-never sees your passphrase, your unencrypted key or your unencrypted files.
-Chunking and id generation are also based on your key to improve
-your privacy.
+Encrypt and sign your backups with the Borg key to prevent anyone
+from reading or forging them unless they have the Borg key \fIand\fP
+know the passphrase.
 .IP 6. 3
-Use the key when extracting files to decrypt them and to verify that the contents of
-the backups have not been accidentally or maliciously altered.
+Use the Borg key to decrypt and thus access the data stored in your
+repository, e.g. when extracting files. The contents can also be
+verified to detect accidental corruption or malicious tampering.
 .UNINDENT
+.sp
+As you can see, you always need \fIboth\fP the Borg key and passphrase to
+access your data. Thus it\(aqs crucial to keep a backup of your key
+\fIoutside\fP both the repository and the system you create backups of.
+You can easily run into a \(dqleaving your keys inside your car\(dq situation
+otherwise. See \fIborg_key_export\fP to create a backup of your key
+(e.g., by printing it on paper).
+.sp
+Encryption is done locally \- i.e., if you back up to a remote machine,
+the remote machine neither sees your passphrase, nor your unencrypted
+Borg key, nor your unencrypted files. Chunking and ID generation are
+based on your key to improve privacy.
+.sp
+\fBAbout hardware acceleration:\fP
+.sp
+Borg encrypts data with AES, which is pretty fast thanks to hardware
+acceleration on basically all modern Intel, AMD, and ARM CPUs since
+around the early 2010s (very cheap models since the mid\-2010s).
+.sp
+As the hashing algorithm, Borg can use either SHA256 or BLAKE2b. ARM
+CPUs support hardware\-accelerated SHA256 hashing since ARMv7 with NEON
+(around 2011), or ARMv8 (around 2013). AMD CPUs support it since Zen 1
+(around 2017), i.e. all AMD Ryzen CPUs. Intel CPUs support it since Ice
+Lake on mobile (10th gen, around 2021), and Rocket Lake on desktop
+(11th gen, around 2021). Very cheap models have received support a few
+years later. If your CPU doesn\(aqt support hardware\-accelerated SHA256
+hashing, you might want to give BLAKE2b hashing a try \- it\(aqs likely
+faster then. So, instead of \fBrepokey\fP mode, use \fBrepokey\-blake2\fP
+(or any of the other \fB\-blake2\fP modes for that matter).
+.sp
+Hardware acceleration is always used automatically when available.
 .SS Picking a passphrase
 .sp
-Make sure you use a good passphrase. Not too short, not too simple. The real
-encryption / decryption key is encrypted with / locked by your passphrase.
-If an attacker gets your key, he can\(aqt unlock and use it without knowing the
-passphrase.
+Make sure you use a good passphrase. Not too short, not too simple. The
+real encryption / decryption key is encrypted with / locked by your
+passphrase. If an attacker gets your borg key, they can\(aqt unlock and use
+it without knowing the passphrase.
 .sp
-Be careful with special or non\-ascii characters in your passphrase:
+Be careful with special or non\-ASCII characters in your passphrase:
 .INDENT 0.0
 .IP \(bu 2
-Borg processes the passphrase as unicode (and encodes it as utf\-8),
-so it does not have problems dealing with even the strangest characters.
+Borg processes the passphrase as Unicode (and encodes it as UTF\-8), so
+it does not have problems dealing with even the strangest characters.
 .IP \(bu 2
-BUT: that does not necessarily apply to your OS / VM / keyboard configuration.
+BUT: that does not necessarily apply to your OS / VM / keyboard
+configuration.
 .UNINDENT
 .sp
-So better use a long passphrase made from simple ascii chars than one that
-includes non\-ascii stuff or characters that are hard/impossible to enter on
-a different keyboard layout.
-.sp
-You can change your passphrase for existing repos at any time, it won\(aqt affect
-the encryption/decryption key or other secrets.
-.SS More encryption modes
+So it is better to use a long passphrase made from simple ASCII
+characters than one that includes non\-ASCII characters or characters
+that are hard or impossible to enter on a different keyboard layout.
 .sp
-Only use \fB\-\-encryption none\fP if you are OK with anyone who has access to
-your repository being able to read your backups and tamper with their
-contents without you noticing.
+You can change your passphrase for existing repositories at any time; it
+won\(aqt affect the encryption/decryption key or other secrets. See
+\fIborg_key_change\-passphrase\fP\&.
+.SS More about encryption modes
 .sp
-If you want \(dqpassphrase and having\-the\-key\(dq security, use \fB\-\-encryption keyfile\fP\&.
-The key will be stored in your home directory (in \fB~/.config/borg/keys\fP).
+Choosing the right encryption mode isn\(aqt always easy and many factors
+can change which mode is best for you. However, note that you can\(aqt
+really do anything \fIwrong\fP if you choose \fBrepokey\fP with a strong
+passphrase. So, if you\(aqre not sure, choose \fBrepokey\fP (or
+\fBrepokey\-blake2\fP, depending on your hardware, see above).
 .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
-the hashing is done on your local machine.
+Borg supports the following encryption modes:
 .\" nanorst: inline-fill
 .
 .TS
@@ -135,25 +153,26 @@ l|l|l|l.
 T{
 Hash/MAC
 T}	T{
-Not encrypted
-no auth
-T}	T{
-Not encrypted,
-but authenticated
+Not Encrypted
 T}	T{
 Encrypted (AEAD w/ AES)
-and authenticated
+T}
+_
+T{
+Not Authenticated
+T}	T{
+Authenticated
 T}
 _
 T{
 SHA\-256
 T}	T{
-none
+\fBnone\fP
 T}	T{
-\fIauthenticated\fP
+\fBauthenticated\fP
 T}	T{
-repokey
-keyfile
+\fBrepokey\fP
+\fBkeyfile\fP
 T}
 _
 T{
@@ -161,56 +180,106 @@ BLAKE2b
 T}	T{
 n/a
 T}	T{
-\fIauthenticated\-blake2\fP
+\fBauthenticated\-blake2\fP
 T}	T{
-\fIrepokey\-blake2\fP
-\fIkeyfile\-blake2\fP
+\fBrepokey\-blake2\fP
+\fBkeyfile\-blake2\fP
 T}
 .TE
 .\" nanorst: inline-replace
 .
 .sp
-Modes \fImarked like this\fP in the above table are new in Borg 1.1 and are not
-backwards\-compatible with Borg 1.0.x.
+Borg 1.0 and older support \fBnone\fP, \fBrepokey\fP, and \fBkeyfile\fP
+modes only. If you need such old clients to be able to access your
+repo, you can\(aqt use any of the other modes.
 .sp
-On modern Intel/AMD CPUs (except very cheap ones), AES is usually
-hardware\-accelerated.
-BLAKE2b is faster than SHA256 on Intel/AMD 64\-bit CPUs
-(except AMD Ryzen and future CPUs with SHA extensions),
-which makes \fIauthenticated\-blake2\fP faster than \fInone\fP and \fIauthenticated\fP\&.
+\fBAbout modes without encryption:\fP
 .sp
-On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
-than BLAKE2b\-256 there. NEON accelerates AES as well.
+Avoid using \fBnone\fP mode. If you think about using \fBnone\fP mode,
+please reconsider and be absolutely sure. Using any mode other than
+\fBnone\fP allows Borg to detect accidental corruption or malicious
+tampering with the repo. It also prevents denial\-of\-service attacks
+against clients. Instead of \fBnone\fP mode, you likely want to use
+\fBauthenticated\fP mode, or \fBrepokey\fP or \fBkeyfile\fP modes with an
+empty passphrase instead (see below).
 .sp
-Hardware acceleration is always used automatically when available.
+If you don\(aqt want to encrypt your data, use \fBauthenticated\fP or
+\fBauthenticated\-blake2\fP modes. These modes require a passphrase in
+normal operation, but in emergency situations you can access the repo
+without the passphrase with \fBBORG_WORKAROUNDS=authenticated_no_key\fP
+(see \fIenvironment\-variables\fP).
+.sp
+If you just don\(aqt want to choose a passphrase, use \fBkeyfile\fP or
+\fBkeyfile\-blake2\fP modes with an empty passphrase. These modes are
+generally safe even without a passphrase, but keeping an offsite
+backup of the Borg key is also important then. See below for details.
+.sp
+If you can assure that an attacker can\(aqt gain access to your repo, e.g.
+when independently encrypting your repository disk or filesystem, you
+can think about using \fBrepokey\fP or \fBrepokey\-blake2\fP modes with an
+empty passphrase. However, keep in mind that if an attacker still
+somehow manages to gain access, they have full access to your repo. In
+such situations choosing \fBrepokey\fP over \fBauthenticated\fP mode has
+the advantage of allowing you to add a passphrase later using
+\fIborg_key_change\-passphrase\fP\&.
+.sp
+\fBAbout modes with encryption:\fP
+.sp
+With \fBrepokey\fP and \fBrepokey\-blake2\fP modes the key is stored with
+the repo and encrypted with your passphrase. If an attacker gains
+access to your repo and knows the passphrase, he can access and tamper
+with the repo. The repo\(aqs security thus relies on the strength of your
+passphrase. Creating an offsite backup of your Borg key (e.g., by
+printing it on paper) is recommended, see \fIborg_key_export\fP\&.
+.sp
+If you\(aqre thinking about storing the passphrase on the disk of the
+system you\(aqre backing up, consider using the \fBkeyfile\fP method
+instead. It generally provides the same or better security then.
+.sp
+With \fBkeyfile\fP and \fBkeyfile\-blake2\fP modes the key is stored on your
+local machine (in \fB~/.config/borg/keys\fP) instead. An attacker gaining
+access to your repo then needs both the Borg key, and your passphrase to
+access and tamper with the repo. However, if you lose the key, you lose
+access to the repo, too. You \fBmust\fP create an offsite backup of your
+Borg key, e.g. by printing it on paper. Storing a copy of the Borg key
+on the system you\(aqre creating backups of is \fBNOT\fP sufficient. Use
+\fIborg_key_export\fP to create the backup.
+.sp
+The \fBkeyfile\fP and \fBkeyfile\-blake2\fP modes allow for \(dqpassphrase and
+having\-the\-key\(dq security when using a strong passphrase, but can also
+be used with an empty passphrase. Storing a (easily readable)
+passphrase on the disk of the system you\(aqre backing up with
+\fBkeyfile\fP and \fBkeyfile\-blake2\fP modes adds no security over using an
+empty passphrase.
+.sp
+\fBTechnical details:\fP
+.sp
+\fBrepokey\fP and \fBkeyfile\fP use AES\-CTR\-256 for encryption and
+HMAC\-SHA256 for authentication in an encrypt\-then\-MAC (EtM)
+construction. The chunk ID hash is HMAC\-SHA256 (with a separate key).
+These modes are compatible with all Borg versions.
+.sp
+\fBrepokey\-blake2\fP and \fBkeyfile\-blake2\fP are also authenticated
+encryption modes, but use BLAKE2b\-256 instead of HMAC\-SHA256 for
+authentication. The chunk ID hash is a keyed BLAKE2b\-256 hash. These
+modes are only compatible with Borg 1.1 and later.
+.sp
+\fBauthenticated\fP mode uses no encryption, but authenticates repo
+contents through the same HMAC\-SHA256 hash as the \fBrepokey\fP and
+\fBkeyfile\fP modes (it uses it as the chunk ID hash). The key is stored
+like \fBrepokey\fP within the repo. This mode is only compatible with
+Borg 1.1 and later.
+.sp
+\fBauthenticated\-blake2\fP is like \fBauthenticated\fP, but uses the keyed
+BLAKE2b\-256 hash from the other BLAKE2b modes. This mode is only
+compatible with Borg 1.1 and later.
 .sp
-\fIrepokey\fP and \fIkeyfile\fP use AES\-CTR\-256 for encryption and HMAC\-SHA256 for
-authentication in an encrypt\-then\-MAC (EtM) construction. The chunk ID hash
-is HMAC\-SHA256 as well (with a separate key).
-These modes are compatible with Borg 1.0.x.
-.sp
-\fIrepokey\-blake2\fP and \fIkeyfile\-blake2\fP are also authenticated encryption modes,
-but use BLAKE2b\-256 instead of HMAC\-SHA256 for authentication. The chunk ID
-hash is a keyed BLAKE2b\-256 hash.
-These modes are new and \fInot\fP compatible with Borg 1.0.x.
-.sp
-\fIauthenticated\fP mode uses no encryption, but authenticates repository contents
-through the same HMAC\-SHA256 hash as the \fIrepokey\fP and \fIkeyfile\fP modes (it uses it
-as the chunk ID hash). The key is stored like \fIrepokey\fP\&.
-This mode is new and \fInot\fP compatible with Borg 1.0.x.
-.sp
-\fIauthenticated\-blake2\fP is like \fIauthenticated\fP, but uses the keyed BLAKE2b\-256 hash
-from the other blake2 modes.
-This mode is new and \fInot\fP compatible with Borg 1.0.x.
-.sp
-\fInone\fP mode uses no encryption and no authentication. It uses SHA256 as chunk
-ID hash. This mode is not recommended, you should rather consider using an authenticated
-or authenticated/encrypted mode. This mode has possible denial\-of\-service issues
-when running \fBborg create\fP on contents controlled by an attacker.
-Use it only for new repositories where no encryption is wanted \fBand\fP when compatibility
-with 1.0.x is important. If compatibility with 1.0.x is not important, use
-\fIauthenticated\-blake2\fP or \fIauthenticated\fP instead.
-This mode is compatible with Borg 1.0.x.
+\fBnone\fP mode uses no encryption and no authentication. It uses SHA256
+as chunk ID hash. This mode is not recommended. You should instead
+consider using an authenticated or authenticated/encrypted mode. This
+mode has possible denial\-of\-service issues when running \fBborg create\fP
+on contents controlled by an attacker. See above for alternatives.
+This mode is compatible with all Borg versions.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-PASSPHRASE" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .SH SYNOPSIS
@@ -35,12 +35,12 @@ borg-key-change-passphrase \- Change repository key file passphrase
 borg [common options] key change\-passphrase [options] [REPOSITORY]
 .SH DESCRIPTION
 .sp
-The key files used for repository encryption are optionally passphrase
+The key files used for repository encryption are optionally passphrase\-
 protected. This command can be used to change this passphrase.
 .sp
 Please note that this command only changes the passphrase, but not any
-secret protected by it (like e.g. encryption/MAC keys or chunker seed).
-Thus, changing the passphrase after passphrase and borg key got compromised
+secret protected by it (e.g., encryption/MAC keys or the chunker seed).
+Thus, changing the passphrase after the passphrase and Borg key were compromised
 does not protect future (nor past) backups to the same repository.
 .SH OPTIONS
 .sp

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .SH SYNOPSIS
@@ -36,15 +36,15 @@ borg [common options] key export [options] [REPOSITORY] [PATH]
 .SH DESCRIPTION
 .sp
 If repository encryption is used, the repository is inaccessible
-without the key. This command allows one to backup this essential key.
+without the key. This command allows one to back up this essential key.
 Note that the backup produced does not include the passphrase itself
-(i.e. the exported key stays encrypted). In order to regain access to a
+(i.e., the exported key stays encrypted). In order to regain access to a
 repository, one needs both the exported key and the original passphrase.
 .sp
 There are three backup formats. The normal backup format is suitable for
 digital storage as a file. The \fB\-\-paper\fP backup format is optimized
-for printing and typing in while importing, with per line checks to
-reduce problems with manual input. The \fB\-\-qr\-html\fP creates a printable
+for printing and typing in while importing, with per\-line checks to
+reduce problems with manual input. The \fB\-\-qr\-html\fP option creates a printable
 HTML template with a QR code and a copy of the \fB\-\-paper\fP\-formatted key.
 .sp
 For repositories using keyfile encryption the key is saved locally
@@ -52,9 +52,9 @@ on the system that is capable of doing backups. To guard against loss
 of this key, the key needs to be backed up independently of the main
 data backup.
 .sp
-For repositories using the repokey encryption the key is saved in the
+For repositories using repokey encryption, the key is saved in the
 repository in the config file. A backup is thus not strictly needed,
-but guards against the repository becoming inaccessible if the file
+but it guards against the repository becoming inaccessible if the file
 is damaged for some reason.
 .sp
 Examples:

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-KEY-IMPORT" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .SH SYNOPSIS
@@ -39,12 +39,12 @@ This command restores a key previously backed up with the export command.
 .sp
 If the \fB\-\-paper\fP option is given, the import will be an interactive
 process in which each line is checked for plausibility before
-proceeding to the next line. For this format PATH must not be given.
+proceeding to the next line. For this format, PATH must not be provided.
 .sp
 For repositories using keyfile encryption, the key file which \fBborg key
 import\fP writes to depends on several factors. If the \fBBORG_KEY_FILE\fP
 environment variable is set and non\-empty, \fBborg key import\fP creates
-or overwrites that file named by \fB$BORG_KEY_FILE\fP\&. Otherwise, \fBborg
+or overwrites the file named by \fB$BORG_KEY_FILE\fP\&. Otherwise, \fBborg
 key import\fP searches in the \fB$BORG_KEYS_DIR\fP directory for a key file
 associated with the repository. If a key file is found in
 \fB$BORG_KEYS_DIR\fP, \fBborg key import\fP overwrites it; otherwise, \fBborg

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-KEY-MIGRATE-TO-REPOKEY" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .SH SYNOPSIS
@@ -38,10 +38,10 @@ borg [common options] key migrate\-to\-repokey [options] [REPOSITORY]
 This command migrates a repository from passphrase mode (removed in Borg 1.0)
 to repokey mode.
 .sp
-You will be first asked for the repository passphrase (to open it in passphrase
-mode). This is the same passphrase as you used to use for this repo before 1.0.
+You will first be asked for the repository passphrase (to open it in passphrase
+mode). This is the same passphrase you used for this repository before 1.0.
 .sp
-It will then derive the different secrets from this passphrase.
+The different secrets will then be derived from this passphrase.
 .sp
 Then you will be asked for a new passphrase (twice, for safety). This
 passphrase will be used to protect the repokey (which contains these same
@@ -49,7 +49,7 @@ secrets in encrypted form). You may use the same passphrase as you used to
 use, but you may also use a different one.
 .sp
 After migrating to repokey mode, you can change the passphrase at any time.
-But please note: the secrets will always stay the same and they could always
+Please note: the secrets will always stay the same, and they could always
 be derived from your (old) passphrase\-mode passphrase.
 .SH OPTIONS
 .sp

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-KEY" "1" "2025-10-31" "" "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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-LIST" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .SH SYNOPSIS
@@ -150,7 +150,7 @@ $ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern
 .SH NOTES
 .SS The FORMAT specifier syntax
 .sp
-The \fB\-\-format\fP option uses python\(aqs format string syntax <https://docs.python.org/3.9/library/string.html#formatstrings>
+The \fB\-\-format\fP option uses Python\(aqs format string syntax <https://docs.python.org/3.9/library/string.html#formatstrings>
 \&.
 .sp
 Examples:

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-MOUNT" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -39,20 +39,20 @@ This command mounts a repository or an archive as a FUSE filesystem.
 This can be useful for browsing or restoring individual files.
 .sp
 When restoring, take into account that the current FUSE implementation does
-not support special fs flags and ACLs.
+not support special filesystem flags and ACLs.
 .sp
 When mounting a repository, the top directories will be named like the
 archives and the directory structure below these will be loaded on\-demand from
 the repository when entering these directories, so expect some delay.
 .sp
 Unless the \fB\-\-foreground\fP option is given the command will run in the
-background until the filesystem is \fBumounted\fP\&.
+background until the filesystem is \fBunmounted\fP\&.
 .sp
 Performance tips:
 .INDENT 0.0
 .IP \(bu 2
 when doing a \(dqwhole repository\(dq mount:
-do not enter archive dirs if not needed, this avoids on\-demand loading.
+do not enter archive directories if not needed; this avoids on\-demand loading.
 .IP \(bu 2
 only mount a specific archive, not the whole repository.
 .IP \(bu 2
@@ -78,7 +78,7 @@ override the user and group ids of all files (i.e., \fBborg mount \-o
 uid=1000,gid=1000\fP).
 .sp
 The man page references \fBuser_id\fP and \fBgroup_id\fP mount options
-(implemented by fuse) which specify the user and group id of the mount owner
+(implemented by FUSE) which specify the user and group id of the mount owner
 (aka, the user who does the mounting). It is set automatically by libfuse (or
 the filesystem if libfuse is not used). However, you should not specify these
 manually. Unlike the \fBuid\fP and \fBgid\fP mount options which affect all files,
@@ -89,7 +89,7 @@ Additional mount options supported by borg:
 .INDENT 0.0
 .IP \(bu 2
 \fBversions\fP: when used with a repository mount, this gives a merged, versioned
-view of the files in the archives. EXPERIMENTAL, layout may change in future.
+view of the files in the archives. EXPERIMENTAL; the layout may change in the future.
 .IP \(bu 2
 \fBallow_damaged_files\fP: by default damaged files (where missing chunks were
 replaced with runs of zeros by \fBborg check \-\-repair\fP) are not readable and
@@ -111,6 +111,13 @@ to unintentionally delete data.
 .sp
 When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
 but other signals or crashes do not.
+.sp
+Debugging:
+.sp
+\fBborg mount\fP usually daemonizes and the daemon process sends stdout/stderr
+to /dev/null. Thus, you need to either use \fB\-f / \-\-foreground\fP to make it stay
+in the foreground and not daemonize, or use \fBBORG_LOGGING_CONF\fP to reconfigure
+the logger to output to a file.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

docs/man/borg-patterns.1

@@ -27,20 +27,31 @@ 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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-PATTERNS" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
 .sp
-The path/filenames used as input for the pattern matching start from the
+The path/filenames used as input for the pattern matching start with 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
-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\&.
+Be careful, your patterns must match the archived paths:
+.INDENT 0.0
+.IP \(bu 2
+Archived paths never start with a leading slash (\(aq/\(aq), nor with \(aq.\(aq, nor with \(aq..\(aq.
+.INDENT 2.0
+.IP \(bu 2
+When you back up absolute paths like \fB/home/user\fP, the archived
+paths start with \fBhome/user\fP\&.
+.IP \(bu 2
+When you back up relative paths like \fB\&./src\fP, the archived paths
+start with \fBsrc\fP\&.
+.IP \(bu 2
+When you back up relative paths like \fB\&../../src\fP, the archived paths
+start with \fBsrc\fP\&.
+.UNINDENT
+.UNINDENT
 .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
@@ -50,6 +61,8 @@ included but not its content. If it does not end with a slash, such as
 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).
+.sp
+The default pattern style for \fB\-\-exclude\fP differs from \fB\-\-pattern\fP, see below.
 .INDENT 0.0
 .TP
 .B Fnmatch <https://docs.python.org/3/library/fnmatch.html>
@@ -148,6 +161,17 @@ Examples:
 .INDENT 3.5
 .sp
 .EX
+# Exclude a directory anywhere in the tree named \(ga\(gasteamapps/common\(ga\(ga
+# (and everything below it), regardless of where it appears:
+$ borg create \-e \(aqsh:**/steamapps/common/**\(aq backup /
+
+# Exclude the contents of \(ga\(ga/home/user/.cache\(ga\(ga:
+$ borg create \-e \(aqsh:home/user/.cache/**\(aq backup /home/user
+$ borg create \-e home/user/.cache/ backup /home/user
+
+# The file \(aq/home/user/.cache/important\(aq is *not* backed up:
+$ borg create \-e home/user/.cache/ backup / /home/user/.cache/important
+
 # Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq:
 $ borg create \-e \(aq*.o\(aq backup /
 
@@ -155,12 +179,6 @@ $ borg create \-e \(aq*.o\(aq backup /
 # not \(aq/home/user/importantjunk\(aq or \(aq/etc/junk\(aq:
 $ borg create \-e \(aqhome/*/junk\(aq backup /
 
-# Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself:
-$ borg create \-e home/user/cache/ backup /
-
-# The file \(aq/home/user/cache/important\(aq is *not* backed up:
-$ borg create \-e home/user/cache/ backup / /home/user/cache/important
-
 # The contents of directories in \(aq/home\(aq are not backed up when their name
 # ends in \(aq.tmp\(aq
 $ borg create \-\-exclude \(aqre:^home/[^/]+\e.tmp/\(aq backup /
@@ -192,11 +210,13 @@ 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
+.B Pattern style prefix \fBP\fP (only useful within patterns files)
 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.
+All patterns following this line in the same patterns file will use this
+style until another style is specified or the end of the file is reached.
+When the current patterns file is finished, the default pattern style will
+reset.
 .TP
 .B Exclude pattern prefix \fB\-\fP
 Use the prefix \fB\-\fP, followed by a pattern, to define an exclusion.

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-PLACEHOLDERS" "1" "2025-10-31" "" "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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-PRUNE" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS
@@ -74,9 +74,9 @@ up to 7 most recent days with backups (days without backups do not count).
 The rules are applied from secondly to yearly, and backups selected by previous
 rules do not count towards those of later rules. The time that each backup
 starts is used for pruning purposes. Dates and times are interpreted in
-the local timezone, and weeks go from Monday to Sunday. Specifying a
-negative number of archives to keep means that there is no limit. As of borg
-1.2.0, borg will retain the oldest archive if any of the secondly, minutely,
+the local time zone, and weeks go from Monday to Sunday. Specifying a
+negative number of archives to keep means that there is no limit. As of Borg
+1.2.0, Borg will retain the oldest archive if any of the secondly, minutely,
 hourly, daily, weekly, monthly, quarterly, 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
@@ -164,42 +164,42 @@ only consider archive names matching the glob. sh: rules apply (without actually
 .UNINDENT
 .SH EXAMPLES
 .sp
-Be careful, prune is a potentially dangerous command, it will remove backup
+Be careful: prune is a potentially dangerous command; it will remove backup
 archives.
 .sp
-The default of prune is to apply to \fBall archives in the repository\fP unless
-you restrict its operation to a subset of the archives using \fB\-\-glob\-archives\fP\&.
-When using \fB\-\-glob\-archives\fP, be careful to choose a good matching pattern \-
-e.g. do not use \(dqfoo*\(dq if you do not also want to match \(dqfoobar\(dq.
+By default, prune applies to \fBall archives in the repository\fP unless you
+restrict its operation to a subset of the archives using \fB\-\-glob\-archives\fP\&.
+When using \fB\-\-glob\-archives\fP, be careful to choose a good matching pattern —
+for example, do not use \(dqfoo*\(dq if you do not also want to match \(dqfoobar\(dq.
 .sp
 It is strongly recommended to always run \fBprune \-v \-\-list \-\-dry\-run ...\fP
-first so you will see what it would do without it actually doing anything.
+first, so you can see what it would do without actually doing anything.
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .EX
-# Keep 7 end of day and 4 additional end of week archives.
+# Keep 7 end\-of\-day and 4 additional end\-of\-week archives.
 # Do a dry\-run without actually deleting anything.
 $ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4 /path/to/repo
 
 # Same as above but only apply to archive names starting with the hostname
 # of the machine followed by a \(dq\-\(dq character:
 $ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-glob\-archives=\(aq{hostname}\-*\(aq /path/to/repo
-# actually free disk space:
+# Actually free disk space:
 $ borg compact /path/to/repo
 
-# Keep 7 end of day, 4 additional end of week archives,
-# and an end of month archive for every month:
+# Keep 7 end\-of\-day, 4 additional end\-of\-week archives,
+# and an end\-of\-month archive for every month:
 $ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
 
-# Keep all backups in the last 10 days, 4 additional end of week archives,
-# and an end of month archive for every month:
+# Keep all backups in the last 10 days, 4 additional end\-of\-week archives,
+# and an end\-of\-month archive for every month:
 $ borg prune \-v \-\-list \-\-keep\-within=10d \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
 .EE
 .UNINDENT
 .UNINDENT
 .sp
-There is also a visualized prune example in \fBdocs/misc/prune\-example.txt\fP\&.
+There is also a visual example of pruning in \fBdocs/misc/prune\-example.txt\fP\&.
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP, \fIborg\-compact(1)\fP

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-RECREATE" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .SH SYNOPSIS
@@ -37,7 +37,7 @@ borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
 .sp
 Recreate the contents of existing archives.
 .sp
-recreate is a potentially dangerous function and might lead to data loss
+Recreate is a potentially dangerous operation and might lead to data loss
 (if used wrongly). BE VERY CAREFUL!
 .sp
 Important: Repository disk space is \fBnot\fP freed until you run \fBborg compact\fP\&.
@@ -55,34 +55,34 @@ Due to how Borg stores compressed size information this might display
 incorrect information for archives that were not recreated at the same time.
 There is no risk of data loss by this.
 .sp
-\fB\-\-chunker\-params\fP will re\-chunk all files in the archive, this can be
+\fB\-\-chunker\-params\fP will re\-chunk all files in the archive; this can be
 used to have upgraded Borg 0.xx or Attic archives deduplicate with
 Borg 1.x archives.
 .sp
 \fBUSE WITH CAUTION.\fP
 Depending on the PATHs and patterns given, recreate can be used to permanently
 delete files from archives.
-When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHS are
+When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHs are
 interpreted. See \fIlist_item_flags\fP in \fBborg create\fP for details.
 .sp
 The archive being recreated is only removed after the operation completes. The
 archive that is built during the operation exists at the same time at
 \(dq<ARCHIVE>.recreate\(dq. The new archive will have a different archive ID.
 .sp
-With \fB\-\-target\fP the original archive is not replaced, instead a new archive is created.
+With \fB\-\-target\fP the original archive is not replaced; instead, a new archive is created.
 .sp
 When rechunking (or recompressing), space usage can be substantial \- expect
 at least the entire deduplicated size of the archives using the previous
-chunker (or compression) params.
+chunker (or compression) parameters.
 .sp
-If you recently ran borg check \-\-repair and it had to fix lost chunks with all\-zero
+If you recently ran \fBborg check \-\-repair\fP and it had to fix lost chunks with all\-zero
 replacement chunks, please first run another backup for the same data and re\-run
-borg check \-\-repair afterwards to heal any archives that had lost chunks which are
+\fBborg check \-\-repair\fP afterwards to heal any archives that had lost chunks which are
 still generated from the input data.
 .sp
-Important: running borg recreate to re\-chunk will remove the chunks_healthy
+Important: running \fBborg recreate\fP to re\-chunk will remove the \fBchunks_healthy\fP
 metadata of all items with replacement chunks, so healing will not be possible
-any more after re\-chunking (it is also unlikely it would ever work: due to the
+anymore after re\-chunking (it is also unlikely it would ever work: due to the
 change of chunking parameters, the missing chunk likely will never be seen again
 even if you still have the data that produced it).
 .SH OPTIONS
@@ -165,22 +165,22 @@ rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH
 .INDENT 3.5
 .sp
 .EX
-# Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
+# Make old (Attic/Borg 0.xx) archives deduplicate with Borg 1.x archives.
 # Archives created with Borg 1.1+ and the default chunker params are skipped
 # (archive ID stays the same).
 $ borg recreate /mnt/backup \-\-chunker\-params default \-\-progress
 
-# Create a backup with little but fast compression
+# Create a backup with low but fast compression.
 $ borg create /mnt/backup::archive /some/files \-\-compression lz4
-# Then compress it \- this might take longer, but the backup has already completed,
+# Then compress it — this might take longer, but the backup has already completed,
 # so no inconsistencies from a long\-running backup job.
 $ borg recreate /mnt/backup::archive \-\-recompress \-\-compression zlib,9
 
 # Remove unwanted files from all archives in a repository.
-# Note the relative path for the \-\-exclude option \- archives only contain relative paths.
+# Note the relative path for the \-\-exclude option — archives only contain relative paths.
 $ borg recreate /mnt/backup \-\-exclude home/icke/Pictures/drunk_photos
 
-# Change archive comment
+# Change the archive comment.
 $ borg create \-\-comment \(dqThis is a comment\(dq /mnt/backup::archivename ~
 $ borg info /mnt/backup::archivename
 Name: archivename

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-RENAME" "1" "2025-10-31" "" "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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-SERVE" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .SH SYNOPSIS
@@ -56,7 +56,7 @@ Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository
 .UNINDENT
 .SH EXAMPLES
 .sp
-\fBborg serve\fP has special support for ssh forced commands (see \fBauthorized_keys\fP
+\fBborg serve\fP has special support for SSH forced commands (see \fBauthorized_keys\fP
 example below): if the environment variable SSH_ORIGINAL_COMMAND is set it will
 ignore some options given on the command line and use the values from the
 variable instead. This only applies to a carefully controlled allowlist of safe
@@ -71,22 +71,22 @@ giving up and aborting the operation when another process is holding a lock.
 .UNINDENT
 .sp
 Environment variables (such as BORG_XXX) contained in the original
-command sent by the client are \fInot\fP interpreted, but ignored. If BORG_XXX environment
-variables should be set on the \fBborg serve\fP side, then these must be set in system\-specific
+command sent by the client are \fInot\fP interpreted; they are ignored. If BORG_XXX environment
+variables need to be set on the \fBborg serve\fP side, then these must be set in system\-specific
 locations like \fB/etc/environment\fP or in the forced command itself (example below).
 .INDENT 0.0
 .INDENT 3.5
 .sp
 .EX
-# Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
+# Allow an SSH key pair to only run borg, and only have access to /path/to/repo.
 # Use key options to disable unneeded and potentially dangerous SSH functionality.
-# This will help to secure an automated remote backup system.
+# This helps secure an automated remote backup system.
 $ cat ~/.ssh/authorized_keys
 command=\(dqborg serve \-\-restrict\-to\-path /path/to/repo\(dq,restrict ssh\-rsa AAAAB3[...]
 
-# Set a BORG_XXX environment variable on the \(dqborg serve\(dq side
+# Set a BORG_XXX environment variable on the \(ga\(gaborg serve\(ga\(ga side.
 $ cat ~/.ssh/authorized_keys
-command=\(dqexport BORG_XXX=value; borg serve [...]\(dq,restrict ssh\-rsa [...]
+command=\(dqBORG_XXX=value borg serve [...]\(dq,restrict ssh\-rsa [...]
 .EE
 .UNINDENT
 .UNINDENT
@@ -94,13 +94,14 @@ command=\(dqexport BORG_XXX=value; borg serve [...]\(dq,restrict ssh\-rsa [...]
 \fBNOTE:\fP
 .INDENT 0.0
 .INDENT 3.5
-The examples above use the \fBrestrict\fP directive. This does automatically
-block potential dangerous ssh features, even when they are added in a future
-update. Thus, this option should be preferred.
-.sp
-If you\(aqre using openssh\-server < 7.2, however, you have to explicitly specify
-the ssh features to restrict and cannot simply use the restrict option as it
-has been introduced in v7.2. We recommend to use
+The examples above use the \fBrestrict\fP directive and assume a POSIX\-compliant
+shell set as the user\(aqs login shell.
+This automatically blocks potentially dangerous SSH features, even when
+they are added in a future update. Thus, this option should be preferred.
+.sp
+If you\(aqre using OpenSSH server < 7.2, however, you have to explicitly specify
+the SSH features to restrict and cannot simply use the \fBrestrict\fP option as it
+was introduced in v7.2. We recommend using
 \fBno\-port\-forwarding,no\-X11\-forwarding,no\-pty,no\-agent\-forwarding,no\-user\-rc\fP
 in this case.
 .UNINDENT
@@ -126,9 +127,9 @@ Host backupserver
 .UNINDENT
 .UNINDENT
 .sp
-Replacing \fBbackupserver\fP with the hostname, FQDN or IP address of the borg server.
+Replace \fBbackupserver\fP with the hostname, FQDN, or IP address of the Borg server.
 .sp
-This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the ssh client process will be terminated, causing the borg process to terminate gracefully.
+This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the SSH client process will be terminated, causing the Borg process to terminate gracefully.
 .sp
 On the server side\(aqs \fBsshd\fP configuration file (typically \fB/etc/ssh/sshd_config\fP):
 .INDENT 0.0
@@ -141,11 +142,31 @@ ClientAliveCountMax 30
 .UNINDENT
 .UNINDENT
 .sp
-This will cause the server to send a keep alive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server\(aqs sshd process will be terminated, causing the \fBborg serve\fP process to terminate gracefully and release the lock on the repository.
+This will cause the server to send a keepalive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server\(aqs sshd process will be terminated, causing the \fBborg serve\fP process to terminate gracefully and release the lock on the repository.
 .sp
-If you then run borg commands with \fB\-\-lock\-wait 600\fP, this gives sufficient time for the borg serve processes to terminate after the SSH connection is torn down after the 300 second wait for the keepalives to fail.
+If you then run Borg commands with \fB\-\-lock\-wait 600\fP, this gives sufficient time for the \fBborg serve\fP processes to terminate after the SSH connection is torn down following the 300\-second wait for the keepalives to fail.
 .sp
 You may, of course, modify the timeout values demonstrated above to values that suit your environment and use case.
+.sp
+When the client is untrusted, it is a good idea to set the backup
+user\(aqs shell to a simple implementation (\fB/bin/sh\fP is only an example and may or may
+not be such a simple implementation):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+chsh \-s /bin/sh BORGUSER
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+Because the configured shell is used by openssh <https://www.openssh.com/>
+
+to execute the command configured through the \fBauthorized_keys\fP file
+using \fB\(dq$SHELL\(dq \-c \(dq$COMMAND\(dq\fP,
+setting a minimal shell implementation reduces the attack surface
+compared to when a feature\-rich and complex shell implementation is
+used.
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-UMOUNT" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .SH SYNOPSIS
@@ -35,7 +35,7 @@ borg-umount \- un-mount the FUSE filesystem
 borg [common options] umount [options] MOUNTPOINT
 .SH DESCRIPTION
 .sp
-This command un\-mounts a FUSE filesystem that was mounted with \fBborg mount\fP\&.
+This command unmounts a FUSE filesystem that was mounted with \fBborg mount\fP\&.
 .sp
 This is a convenience wrapper that just calls the platform\-specific shell
 command \- usually this is either umount or fusermount \-u.
@@ -106,7 +106,7 @@ $ echo \(aq/mnt/backup::root\-2016\-02\-15 /tmp/myarchive fuse.borgfs defaults,n
 $ mount /tmp/myrepo
 $ mount /tmp/myarchive
 $ ls /tmp/myrepo
-root\-2016\-02\-01 root\-2016\-02\-2015
+root\-2016\-02\-01 root\-2016\-02\-15
 $ ls /tmp/myarchive
 bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt  root  sbin  srv  tmp  usr  var
 .EE

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-UPGRADE" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .SH SYNOPSIS
@@ -60,8 +60,8 @@ archives that are not TAM authenticated yet.
 This is a convenient method to just trust all archives present \- if
 an archive does not have TAM authentication yet, a TAM will be added.
 Archives created by old borg versions < 1.0.9 do not have TAMs.
-Archives created by newer borg version should have TAMs already.
-If you have a high risk environment, you should not just run this,
+Archives created by newer borg versions should have TAMs already.
+If you have a high\-risk environment, you should not just run this,
 but first verify that the archives are authentic and not malicious
 (== have good content, have a good timestamp).
 Borg 1.2.5+ needs all archives to be TAM authenticated for safety reasons.
@@ -101,7 +101,7 @@ with the old chunks in the upgraded repository.
 See \fB\-\-chunker\-params\fP option of \fBborg create\fP and \fBborg recreate\fP\&.
 .sp
 \fBborg upgrade\fP will change the magic strings in the repository\(aqs
-segments to match the new Borg magic strings. The keyfiles found in
+segments to match the new Borg magic strings. The key files found in
 $ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
 copied to $BORG_KEYS_DIR or ~/.config/borg/keys.
 .sp
@@ -109,11 +109,11 @@ The cache files are converted, from $ATTIC_CACHE_DIR or
 ~/.cache/attic to $BORG_CACHE_DIR or ~/.cache/borg, but the
 cache layout between Borg and Attic changed, so it is possible
 the first backup after the conversion takes longer than expected
-due to the cache resync.
+due to the cache re\-sync.
 .sp
 Upgrade should be able to resume if interrupted, although it
 will still iterate over all segments. If you want to start
-from scratch, use \fIborg delete\fP over the copied repository to
+from scratch, use \fBborg delete\fP over the copied repository to
 make sure the cache files are also removed:
 .INDENT 0.0
 .INDENT 3.5
@@ -190,13 +190,13 @@ no key file found for repository
 .EE
 .UNINDENT
 .UNINDENT
-.SS Upgrading a passphrase encrypted attic repo
+.SS Upgrading a passphrase\-encrypted Attic repo
 .sp
-attic offered a \(dqpassphrase\(dq encryption mode, but this was removed in borg 1.0
+Attic offered a \(dqpassphrase\(dq encryption mode, but this was removed in Borg 1.0
 and replaced by the \(dqrepokey\(dq mode (which stores the passphrase\-protected
-encryption key into the repository config).
+encryption key in the repository config).
 .sp
-Thus, to upgrade a \(dqpassphrase\(dq attic repo to a \(dqrepokey\(dq borg repo, 2 steps
+Thus, to upgrade a \(dqpassphrase\(dq Attic repo to a \(dqrepokey\(dq Borg repo, two steps
 are needed, in this order:
 .INDENT 0.0
 .IP \(bu 2

docs/man/borg-version.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-VERSION" "1" "2025-04-18" "" "borg backup tool"
+.TH "BORG-VERSION" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-version \- Display the borg client / borg server version
 .SH SYNOPSIS
@@ -35,12 +35,12 @@ borg-version \- Display the borg client / borg server version
 borg [common options] version [options] [REPOSITORY]
 .SH DESCRIPTION
 .sp
-This command displays the borg client version / borg server version.
+This command displays the Borg client version / Borg server version.
 .sp
-If a local repo is given, the client code directly accesses the repository,
+If a local repository is given, the client code directly accesses the repository,
 thus we show the client version also as the server version.
 .sp
-If a remote repo is given (e.g. ssh:), the remote borg is queried and
+If a remote repository is given (e.g., ssh:), the remote Borg is queried and
 its version is displayed as the server version.
 .sp
 Examples:
@@ -59,10 +59,10 @@ $ borg version ssh://borg@borgbackup:repo
 .UNINDENT
 .UNINDENT
 .sp
-Due to the version tuple format used in borg client/server negotiation, only
-a simplified version is displayed (as provided by borg.version.format_version).
+Due to the version tuple format used in Borg client/server negotiation, only
+a simplified version is displayed (as provided by \fBborg.version.format_version\fP).
 .sp
-There is also borg \-\-version to display a potentially more precise client version.
+There is also \fBborg \-\-version\fP to display a potentially more precise client version.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

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" "2025-04-18" "" "borg backup tool"
+.TH "BORG-WITH-LOCK" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .SH SYNOPSIS
@@ -46,15 +46,15 @@ $ borg with\-lock /mnt/borgrepo rsync \-av /mnt/borgrepo /somewhere/else/borgrep
 .UNINDENT
 .sp
 It will first try to acquire the lock (make sure that no other operation is
-running in the repo), then execute the given command as a subprocess and wait
-for its termination, release the lock and return the user command\(aqs return
-code as borg\(aqs return code.
+running in the repository), then execute the given command as a subprocess and wait
+for its termination, release the lock, and return the user command\(aqs return
+code as Borg\(aqs return code.
 .sp
 \fBNOTE:\fP
 .INDENT 0.0
 .INDENT 3.5
 If you copy a repository with the lock held, the lock will be present in
-the copy. Thus, before using borg on the copy from a different host,
+the copy. Thus, before using Borg on the copy from a different host,
 you need to use \(dqborg break\-lock\(dq on the copied repository, because
 Borg is cautious and does not automatically remove stale locks made by a different host.
 .UNINDENT

docs/man/borg.1

@@ -28,7 +28,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" "2025-04-18" "" "borg backup tool"
+.TH "BORG" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS
@@ -461,6 +461,12 @@ When set to no (default: yes), system information (like OS, Python version, ...)
 exceptions is not shown.
 Please only use for good reasons as it makes issues harder to analyze.
 .TP
+.B BORG_MSGPACK_VERSION_CHECK
+Controls whether Borg checks the \fBmsgpack\fP version.
+The default is \fByes\fP (strict check). Set to \fBno\fP to disable the version check and
+allow any installed \fBmsgpack\fP version. Use this at your own risk; malfunctioning or
+incompatible \fBmsgpack\fP versions may cause subtle bugs or repository data corruption.
+.TP
 .B BORG_FUSE_IMPL
 Choose the lowlevel FUSE implementation borg shall use for \fBborg mount\fP\&.
 This is a comma\-separated list of implementation names, they are tried in the
@@ -957,7 +963,7 @@ aka \fIBSD flags\fP\&. The Linux set of flags [1] is portable across platforms.
 The BSDs define additional flags.
 .SH SEE ALSO
 .sp
-\fIborg\-common(1)\fP for common command line options
+\fIborg\-common(1)\fP for common command\-line options
 .sp
 \fIborg\-init(1)\fP,
 \fIborg\-create(1)\fP, \fIborg\-mount(1)\fP, \fIborg\-extract(1)\fP,

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" "2025-04-18" "" "borg backup tool"
+.TH "BORGFS" "1" "2025-10-31" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -39,20 +39,20 @@ This command mounts a repository or an archive as a FUSE filesystem.
 This can be useful for browsing or restoring individual files.
 .sp
 When restoring, take into account that the current FUSE implementation does
-not support special fs flags and ACLs.
+not support special filesystem flags and ACLs.
 .sp
 When mounting a repository, the top directories will be named like the
 archives and the directory structure below these will be loaded on\-demand from
 the repository when entering these directories, so expect some delay.
 .sp
 Unless the \fB\-\-foreground\fP option is given the command will run in the
-background until the filesystem is \fBumounted\fP\&.
+background until the filesystem is \fBunmounted\fP\&.
 .sp
 Performance tips:
 .INDENT 0.0
 .IP \(bu 2
 when doing a \(dqwhole repository\(dq mount:
-do not enter archive dirs if not needed, this avoids on\-demand loading.
+do not enter archive directories if not needed; this avoids on\-demand loading.
 .IP \(bu 2
 only mount a specific archive, not the whole repository.
 .IP \(bu 2
@@ -78,7 +78,7 @@ override the user and group ids of all files (i.e., \fBborg mount \-o
 uid=1000,gid=1000\fP).
 .sp
 The man page references \fBuser_id\fP and \fBgroup_id\fP mount options
-(implemented by fuse) which specify the user and group id of the mount owner
+(implemented by FUSE) which specify the user and group id of the mount owner
 (aka, the user who does the mounting). It is set automatically by libfuse (or
 the filesystem if libfuse is not used). However, you should not specify these
 manually. Unlike the \fBuid\fP and \fBgid\fP mount options which affect all files,
@@ -89,7 +89,7 @@ Additional mount options supported by borg:
 .INDENT 0.0
 .IP \(bu 2
 \fBversions\fP: when used with a repository mount, this gives a merged, versioned
-view of the files in the archives. EXPERIMENTAL, layout may change in future.
+view of the files in the archives. EXPERIMENTAL; the layout may change in the future.
 .IP \(bu 2
 \fBallow_damaged_files\fP: by default damaged files (where missing chunks were
 replaced with runs of zeros by \fBborg check \-\-repair\fP) are not readable and
@@ -111,6 +111,13 @@ to unintentionally delete data.
 .sp
 When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
 but other signals or crashes do not.
+.sp
+Debugging:
+.sp
+\fBborg mount\fP usually daemonizes and the daemon process sends stdout/stderr
+to /dev/null. Thus, you need to either use \fB\-f / \-\-foreground\fP to make it stay
+in the foreground and not daemonize, or use \fBBORG_LOGGING_CONF\fP to reconfigure
+the logger to output to a file.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

docs/usage/benchmark_crud.rst.inc

@@ -17,7 +17,7 @@ borg benchmark crud
     +-------------------------------------------------------+----------------+----------------------------------------------+
     |                                                       | ``REPOSITORY`` | repository to use for benchmark (must exist) |
     +-------------------------------------------------------+----------------+----------------------------------------------+
-    |                                                       | ``PATH``       | path were to create benchmark input data     |
+    |                                                       | ``PATH``       | path where to create benchmark input data    |
     +-------------------------------------------------------+----------------+----------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                        |
     |                                                                                                                       |
@@ -37,7 +37,7 @@ borg benchmark crud
     REPOSITORY
         repository to use for benchmark (must exist)
     PATH
-        path were to create benchmark input data
+        path where to create benchmark input data
 
 
     :ref:`common_options`
@@ -48,7 +48,7 @@ Description
 
 This command benchmarks borg CRUD (create, read, update, delete) operations.
 
-It creates input data below the given PATH and backups this data into the given REPO.
+It creates input data below the given PATH and backs up this data into the given REPO.
 The REPO must already exist (it could be a fresh empty repo or an existing repo, the
 command will create / read / update / delete some archives named borg-benchmark-crud\* there.
 
@@ -64,17 +64,17 @@ thus the measurement results do not necessarily reflect performance with real da
 Also, due to the kind of content used, no compression is used in these benchmarks.
 
 C- == borg create (1st archive creation, no compression, do not use files cache)
-      C-Z- == all-zero files. full dedup, this is primarily measuring reader/chunker/hasher.
-      C-R- == random files. no dedup, measuring throughput through all processing stages.
+      C-Z- == all-zero files. full deduplication; this primarily measures reader/chunker/hasher.
+      C-R- == random files. no deduplication, measuring throughput through all processing stages.
 
 R- == borg extract (extract archive, dry-run, do everything, but do not write files to disk)
-      R-Z- == all zero files. Measuring heavily duplicated files.
+      R-Z- == all-zero files. Measuring heavily duplicated files.
       R-R- == random files. No duplication here, measuring throughput through all processing
       stages, except writing to disk.
 
 U- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
       The throughput value is kind of virtual here, it does not actually read the file.
-      U-Z- == needs to check the 2 all-zero chunks' existence in the repo.
+      U-Z- == needs to check the two all-zero chunks' existence in the repo.
       U-R- == needs to check existence of a lot of different chunks in the repo.
 
 D- == borg delete archive (delete last remaining archive, measure deletion + compaction)
@@ -82,4 +82,4 @@ D- == borg delete archive (delete last remaining archive, measure deletion + com
       D-R- == many chunks to delete / many segments to compact/remove.
 
 Please note that there might be quite some variance in these measurements.
-Try multiple measurements and having a otherwise idle machine (and network, if you use it).
+Try multiple measurements and have an otherwise idle machine (and network, if you use it).

docs/usage/break-lock.rst.inc

@@ -43,5 +43,5 @@ Description
 ~~~~~~~~~~~
 
 This command breaks the repository and cache locks.
-Please use carefully and only while no borg process (on any machine) is
-trying to access the Cache or the Repository.
+Please use with care and only when no borg process (on any machine) is
+trying to access the cache or the repository.

docs/usage/check.rst.inc

@@ -126,7 +126,7 @@ archive checks, nor enable repair mode. Consequently, if you want to use
 **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
+also do a repository index check. Enabling partial repository checks excludes
 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.
 
@@ -135,13 +135,13 @@ 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``.
+encrypted repositories against attackers without access to the keys. You cannot
+use ``--verify-data`` with ``--repository-only``.
 
 About repair mode
 +++++++++++++++++
 
-The check command is a readonly task by default. If any corruption is found,
+The check command is a read-only 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``.
 

docs/usage/compact.rst.inc

@@ -72,8 +72,15 @@ A segment is compacted if the amount of saved space is above the percentage valu
 given by the ``--threshold`` option. If omitted, a threshold of 10% is used.
 When using ``--verbose``, borg will output an estimate of the freed space.
 
+For maximum compaction, use ``--threshold 0``. This will compact whenever any
+space can be saved and thus rewrites the most data; it can be much slower on
+large repositories. Using ``--threshold 1`` usually achieves nearly the same
+result significantly faster. Higher thresholds (e.g. the default 10) trade
+compaction thoroughness for speed. Note: ``--threshold 100`` will effectively
+compact nothing.
+
 After upgrading borg (server) to 1.2+, you can use ``borg compact --cleanup-commits``
-to clean up the numerous 17byte commit-only segments that borg 1.1 did not clean up
+to clean up the numerous 17-byte commit-only segments that borg 1.1 did not clean up
 due to a bug. It is enough to do that once per repository. After cleaning up the
 commits, borg will also do a normal compaction.
 

docs/usage/config.rst.inc

@@ -68,7 +68,7 @@ This command gets and sets options in a local repository or cache config file.
 For security reasons, this command only works on local repositories.
 
 To delete a config value entirely, use ``--delete``. To list the values
-of the configuration file or the default values, use ``--list``.  To get an existing
+of the configuration file or the default values, use ``--list``. To get an existing
 key, pass only the key name. To set a key, pass both the key name and
 the new value. Keys can be specified in the format "section.name" or
 simply "name"; the section will default to "repository" and "cache" for

docs/usage/create.rst.inc

@@ -99,6 +99,8 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--files-cache MODE``                            | operate files cache in MODE. default: ctime,size,inode                                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--files-changed MODE``                          | specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime                                                                |
+    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--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**                                                                                                                                                                                                                                                           |
@@ -175,6 +177,7 @@ borg create
         --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
+        --files-changed MODE      specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime
         --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.
 
 
@@ -191,18 +194,18 @@ Description
 
 This command creates a backup archive containing all files found while recursively
 traversing all paths specified. Paths are added to the archive as they are given,
-that means if relative paths are desired, the command has to be run from the correct
+which means that if relative paths are desired, the command has to be run from the correct
 directory.
 
 The slashdot hack in paths (recursion roots) is triggered by using ``/./``:
-``/this/gets/stripped/./this/gets/archived`` means to process that fs object, but
+``/this/gets/stripped/./this/gets/archived`` means to process that filesystem object, but
 strip the prefix on the left side of ``./`` from the archived items (in this case,
 ``this/gets/archived`` will be the path in the archived item).
 
-When giving '-' as path, borg will read data from standard input and create a
-file 'stdin' in the created archive from that data. In some cases it's more
-appropriate to use --content-from-command, however. See section *Reading from
-stdin* below for details.
+When giving '-' as a path, Borg will read data from standard input and create a
+file 'stdin' in the created archive from that data. In some cases, it is more
+appropriate to use ``--content-from-command``. See section "Reading from stdin"
+below for details.
 
 The archive will consume almost no disk space for files or parts of files that
 have already been stored in other archives.
@@ -222,41 +225,49 @@ the files cache.
 This comparison can operate in different modes as given by ``--files-cache``:
 
 - ctime,size,inode (default)
-- mtime,size,inode (default behaviour of borg versions older than 1.1.0rc4)
+- mtime,size,inode (default behavior of borg versions older than 1.1.0rc4)
 - ctime,size (ignore the inode number)
 - mtime,size (ignore the inode number)
 - rechunk,ctime (all files are considered modified - rechunk, cache ctime)
 - rechunk,mtime (all files are considered modified - rechunk, cache mtime)
 - disabled (disable the files cache, all files considered modified - rechunk)
 
-inode number: better safety, but often unstable on network filesystems
+inode number: better safety, but often unstable on network file systems
 
 Normally, detecting file modifications will take inode information into
 consideration to improve the reliability of file change detection.
-This is problematic for files located on sshfs and similar network file
-systems which do not provide stable inode numbers, such files will always
+This is problematic for files located on SSHFS and similar network file
+systems which do not provide stable inode numbers; such files will always
 be considered modified. You can use modes without `inode` in this case to
-improve performance, but reliability of change detection might be reduced.
+improve performance, but the reliability of change detection might be reduced.
 
 ctime vs. mtime: safety vs. speed
 
 - ctime is a rather safe way to detect changes to a file (metadata and contents)
-  as it can not be set from userspace. But, a metadata-only change will already
+  as it cannot be set from user space. However, a metadata-only change will already
   update the ctime, so there might be some unnecessary chunking/hashing even
-  without content changes. Some filesystems do not support ctime (change time).
-  E.g. doing a chown or chmod to a file will change its ctime.
+  without content changes. Some file systems do not support ctime (change time).
+  For example, doing a chown or chmod to a file will change its ctime.
 - mtime usually works and only updates if file contents were changed. But mtime
-  can be arbitrarily set from userspace, e.g. to set mtime back to the same value
+  can be arbitrarily set from user space, e.g., to set mtime back to the same value
   it had before a content change happened. This can be used maliciously as well as
-  well-meant, but in both cases mtime based cache modes can be problematic.
+  well-meant, but in both cases mtime-based cache modes can be problematic.
+
+The ``--files-changed`` option controls how Borg detects if a file has changed during backup:
+
+- ctime (default): Use ctime to detect changes. This is the safest option.
+- mtime: Use mtime to detect changes.
+- disabled: Disable the "file has changed while we backed it up" detection completely.
+  This is not recommended unless you know what you're doing, as it could lead to
+  inconsistent backups if files change during the backup process.
 
-The mount points of filesystems or filesystem snapshots should be the same for every
+The mount points of file systems or file system snapshots should be the same for every
 creation of a new archive to ensure fast operation. This is because the file cache that
-is used to determine changed files quickly uses absolute filenames.
+is used to determine changed files quickly uses absolute file names.
 If this is not possible, consider creating a bind mount to a stable location.
 
 The ``--progress`` option shows (from left to right) Original, Compressed and Deduplicated
-(O, C and D, respectively), then the Number of files (N) processed so far, followed by
+(O, C and D, respectively), then the number of files (N) processed so far, followed by
 the currently processed path.
 
 When using ``--stats``, you will get some statistics about how much data was
@@ -284,15 +295,15 @@ only include the objects specified by ``--exclude-if-present`` in your backup,
 and not include any other contents of the containing folder, this can be enabled
 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
+The ``-x`` or ``--one-file-system`` option excludes directories that are mount points (and everything in them).
+It detects mount points 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.
-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.
+In general: be aware that there are directories with device numbers different from their parent, which the kernel
+does not consider mount points, and vice versa.
+Linux examples for this are bind mounts (possibly same device number, but always a mount point) and all
+subvolumes of a Btrfs file system (different device numbers from the parent but not necessarily mount points).
+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.
 
 

docs/usage/diff.rst.inc

@@ -12,43 +12,45 @@ borg diff
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                              |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``REPO::ARCHIVE1``                    | repository location and ARCHIVE1 name                                 |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE2``                          | ARCHIVE2 name (no repository location allowed)                        |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``PATH``                              | paths of items inside the archives to compare; patterns are supported |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    | **options**                                                                                                                                                           |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``--numeric-owner``                   | deprecated, use ``--numeric-ids`` instead                             |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``--numeric-ids``                     | only consider numeric user and group identifiers                      |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``--same-chunker-params``             | Override check of chunker parameters.                                 |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``--sort``                            | Sort the output lines by file path.                                   |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``--content-only``                    | Only compare differences in content (exclude metadata differences)    |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``--json-lines``                      | Format output as JSON Lines.                                          |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    | .. 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          |
-    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                                  |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``REPO::ARCHIVE1``                    | repository location and ARCHIVE1 name                                                                                                     |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``ARCHIVE2``                          | ARCHIVE2 name (no repository location allowed)                                                                                            |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``PATH``                              | paths of items inside the archives to compare; patterns are supported                                                                     |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    | **options**                                                                                                                                                                                                                               |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--numeric-owner``                   | deprecated, use ``--numeric-ids`` instead                                                                                                 |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--numeric-ids``                     | only consider numeric user and group identifiers                                                                                          |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--same-chunker-params``             | Override check of chunker parameters.                                                                                                     |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--sort``                            | Sort the output by path (deprecated, use --sort-by=path).                                                                                 |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--sort-by FIELD[,FIELD...]``        | Advanced sorting: specify field(s) to sort by. Accepts a comma-separated list. Prefix with > for descending or < for ascending (default). |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--content-only``                    | Only compare differences in content (exclude metadata differences)                                                                        |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--json-lines``                      | Format output as JSON Lines.                                                                                                              |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. 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                                                                              |
+    +-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -69,12 +71,13 @@ borg diff
 
 
     options
-        --numeric-owner    deprecated, use ``--numeric-ids`` instead
-        --numeric-ids    only consider numeric user and group identifiers
-        --same-chunker-params    Override check of chunker parameters.
-        --sort     Sort the output lines by file path.
-        --content-only    Only compare differences in content (exclude metadata differences)
-        --json-lines    Format output as JSON Lines. 
+        --numeric-owner                deprecated, use ``--numeric-ids`` instead
+        --numeric-ids                  only consider numeric user and group identifiers
+        --same-chunker-params          Override check of chunker parameters.
+        --sort                         Sort the output by path (deprecated, use --sort-by=path).
+        --sort-by FIELD[,FIELD...]     Advanced sorting: specify field(s) to sort by. Accepts a comma-separated list. Prefix with > for descending or < for ascending (default).
+        --content-only                 Only compare differences in content (exclude metadata differences)
+        --json-lines                   Format output as JSON Lines. 
 
 
     :ref:`common_options`
@@ -93,16 +96,63 @@ Description
 This command finds differences (file contents, user/group/mode) between archives.
 
 A repository location and an archive name must be specified for REPO::ARCHIVE1.
-ARCHIVE2 is just another archive name in same repository (no repository location
+ARCHIVE2 is just another archive name in the same repository (no repository location
 allowed).
 
-For archives created with Borg 1.1 or newer diff automatically detects whether
-the archives are created with the same chunker params. If so, only chunk IDs
+What is compared
++++++++++++++++++
+For each matching item in both archives, Borg reports:
+
+- Content changes: total added/removed bytes within files. If chunker parameters are comparable,
+  Borg compares chunk IDs quickly; otherwise, it compares the content.
+- Metadata changes: user, group, mode, and other metadata shown inline like
+  "[old_mode -> new_mode]" for mode changes. Use ``--content-only`` to suppress metadata changes.
+- Added/removed items: printed as "added SIZE path" or "removed SIZE path".
+
+Output formats
+++++++++++++++
+The default (text) output shows one line per changed path, e.g.::
+
+    +135 B    -252 B [ -rw-r--r-- -> -rwxr-xr-x ] path/to/file
+
+JSON Lines output (``--json-lines``) prints one JSON object per changed path, e.g.::
+
+    {"path": "PATH", "changes": [
+        {"type": "modified", "added": BYTES, "removed": BYTES},
+        {"type": "mode", "old_mode": "-rw-r--r--", "new_mode": "-rwxr-xr-x"},
+        {"type": "added", "size": SIZE},
+        {"type": "removed", "size": SIZE}
+    ]}
+
+Only actual changes are included in the "changes" list. For example, a modified entry with
+added=0 and removed=0 is omitted.
+
+Sorting
+++++++++
+Use ``--sort-by FIELDS`` where FIELDS is a comma-separated list of fields.
+Sorts are applied stably from last to first in the given list. Prepend ">" for
+descending, "<" (or no prefix) for ascending, for example ``--sort-by=">size_added,path"``.
+Supported fields include:
+
+- path: the item path
+- size_added: total bytes added for the item content
+- size_removed: total bytes removed for the item content
+- size_diff: size_added - size_removed (net content change)
+- size: size of the item as stored in ARCHIVE2 (0 for removed items)
+- user, group, uid, gid, ctime, mtime: taken from the item state in ARCHIVE2 when present
+- ctime_diff, mtime_diff: timestamp difference (archive2 - archive1)
+
+The ``--sort`` option is deprecated and only sorts by path.
+
+Performance considerations
+++++++++++++++++++++++++++
+For archives created with Borg 1.1 or newer, diff automatically detects whether
+the archives were created with the same chunker parameters. If so, only chunk IDs
 are compared, which is very fast.
 
-For archives prior to Borg 1.1 chunk contents are compared by default.
-If you did not create the archives with different chunker params,
+For archives prior to Borg 1.1, chunk contents are compared by default.
+If you did not create the archives with different chunker parameters,
 pass ``--same-chunker-params``.
-Note that the chunker params changed from Borg 0.xx to 1.0.
+Note that the chunker parameters changed from Borg 0.xx to 1.0.
 
 For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.

docs/usage/export-tar.rst.inc

@@ -106,7 +106,7 @@ BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported.
 Timestamp resolution is limited to whole seconds, not the nanosecond resolution
 otherwise supported by Borg.
 
-A ``--sparse`` option (as found in borg extract) is not supported.
+A ``--sparse`` option (as found in ``borg extract``) is not supported.
 
 By default the entire archive is extracted but a subset of files and directories
 can be selected by passing a list of ``PATHs`` as arguments.

docs/usage/extract.rst.inc

@@ -101,16 +101,20 @@ borg extract
 Description
 ~~~~~~~~~~~
 
-This command extracts the contents of an archive. By default the entire
-archive is extracted but a subset of files and directories can be selected
-by passing a list of ``PATHs`` as arguments. The file selection can further
-be restricted by using the ``--exclude`` option.
+This command extracts the contents of an archive.
 
+By default, the entire archive is extracted, but a subset of files and directories
+can be selected by passing a list of ``PATH`` arguments. The default interpretation
+for the paths to extract is `pp:` which is a literal path-prefix match. If you want
+to use e.g. a wildcard, you must select a different pattern style such as `sh:` or
+`fm:`. See :ref:`borg_patterns` for more information.
+
+The file selection can be further restricted by using the ``--exclude`` option.
 For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
 
 By using ``--dry-run``, you can do all extraction steps except actually writing the
-output data: reading metadata and data chunks from the repo, checking the hash/hmac,
-decrypting, decompressing.
+output data: reading metadata and data chunks from the repository, checking the hash/HMAC,
+decrypting, and decompressing.
 
 ``--progress`` can be slower than no progress display, since it makes one additional
 pass over the archive metadata.
@@ -121,5 +125,5 @@ pass over the archive metadata.
     so make sure you ``cd`` to the right place before calling ``borg extract``.
 
     When parent directories are not extracted (because of using file/directory selection
-    or any other reason), borg can not restore parent directories' metadata, e.g. owner,
-    group, permission, etc.
+    or any other reason), Borg cannot restore parent directories' metadata, e.g., owner,
+    group, permissions, etc.

docs/usage/help.rst.inc

@@ -6,15 +6,20 @@ borg help patterns
 ~~~~~~~~~~~~~~~~~~
 
 
-The path/filenames used as input for the pattern matching start from the
+The path/filenames used as input for the pattern matching start with the
 currently active recursion root. You usually give the recursion root(s)
 when invoking borg and these can be either relative or absolute paths.
 
-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/``.
+Be careful, your patterns must match the archived paths:
+
+- Archived paths never start with a leading slash ('/'), nor with '.', nor with '..'.
+
+  - When you back up absolute paths like ``/home/user``, the archived
+    paths start with ``home/user``.
+  - When you back up relative paths like ``./src``, the archived paths
+    start with ``src``.
+  - When you back up relative paths like ``../../src``, the archived paths
+    start with ``src``.
 
 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
@@ -25,6 +30,8 @@ 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/**``).
 
+The default pattern style for ``--exclude`` differs from ``--pattern``, see below.
+
 `Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`
     This is the default style for ``--exclude`` and ``--exclude-from``.
     These patterns use a variant of shell pattern syntax, with '\*' matching
@@ -112,6 +119,17 @@ run ``borg create --list --dry-run ...``.
 
 Examples::
 
+    # Exclude a directory anywhere in the tree named ``steamapps/common``
+    # (and everything below it), regardless of where it appears:
+    $ borg create -e 'sh:**/steamapps/common/**' backup /
+
+    # Exclude the contents of ``/home/user/.cache``:
+    $ borg create -e 'sh:home/user/.cache/**' backup /home/user
+    $ borg create -e home/user/.cache/ backup /home/user
+
+    # The file '/home/user/.cache/important' is *not* backed up:
+    $ borg create -e home/user/.cache/ backup / /home/user/.cache/important
+
     # Exclude '/home/user/file.o' but not '/home/user/file.odt':
     $ borg create -e '*.o' backup /
 
@@ -119,12 +137,6 @@ Examples::
     # not '/home/user/importantjunk' or '/etc/junk':
     $ borg create -e 'home/*/junk' backup /
 
-    # Exclude the contents of '/home/user/cache' but not the directory itself:
-    $ borg create -e home/user/cache/ backup /
-
-    # The file '/home/user/cache/important' is *not* backed up:
-    $ borg create -e home/user/cache/ backup / /home/user/cache/important
-
     # The contents of directories in '/home' are not backed up when their name
     # ends in '.tmp'
     $ borg create --exclude 're:^home/[^/]+\.tmp/' backup /
@@ -152,11 +164,13 @@ Root path prefix ``R``
     (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``
+Pattern style prefix ``P`` (only useful within patterns files)
     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.
+    All patterns following this line in the same patterns file will use this
+    style until another style is specified or the end of the file is reached.
+    When the current patterns file is finished, the default pattern style will
+    reset.
 
 Exclude pattern prefix ``-``
     Use the prefix ``-``, followed by a pattern, to define an exclusion.

docs/usage/import-tar.rst.inc

@@ -91,9 +91,9 @@ Description
 
 This command creates a backup archive from a tarball.
 
-When giving '-' as path, Borg will read a tar stream from standard input.
+When giving '-' as a path, Borg will read a tar stream from standard input.
 
-By default (--tar-filter=auto) Borg will detect whether the file is compressed
+By default (``--tar-filter=auto``) Borg will detect whether the file is compressed
 based on its file extension and pipe the file through an appropriate filter:
 
 - .tar.gz or .tgz: gzip -d
@@ -102,11 +102,11 @@ based on its file extension and pipe the file through an appropriate filter:
 - .tar.zstd or .tar.zst: zstd -d
 - .tar.lz4: lz4 -d
 
-Alternatively, a --tar-filter program may be explicitly specified. It should
+Alternatively, a ``--tar-filter`` program may be explicitly specified. It should
 read compressed data from stdin and output an uncompressed tar stream on
 stdout.
 
-Most documentation of borg create applies. Note that this command does not
+Most documentation of ``borg create`` applies. Note that this command does not
 support excluding files.
 
 import-tar is a lossy conversion:

docs/usage/info.rst.inc

@@ -74,11 +74,11 @@ This command displays detailed information about the specified archive or reposi
 
 Please note that the deduplicated sizes of the individual archives do not add
 up to the deduplicated size of the repository ("all archives"), because the two
-are meaning different things:
+mean different things:
 
 This archive / deduplicated size = amount of data stored ONLY for this archive
 = unique chunks of this archive.
-All archives / deduplicated size = amount of data stored in the repo
+All archives / deduplicated size = amount of data stored in the repository
 = all chunks in the repository.
 
 Borg archives can only contain a limited amount of file metadata.

docs/usage/init.rst.inc

@@ -59,135 +59,214 @@ borg init
 Description
 ~~~~~~~~~~~
 
-This command initializes an empty repository. A repository is a filesystem
-directory containing the deduplicated data from zero or more archives.
+This command initializes an empty repository. A repository is a
+filesystem directory containing the deduplicated data from zero or more
+archives.
 
-Encryption mode TLDR
-++++++++++++++++++++
+Encryption mode TL;DR
++++++++++++++++++++++
 
-The encryption mode can only be configured when creating a new repository -
-you can neither configure it on a per-archive basis nor change the
-encryption mode of an existing repository.
+The encryption mode can only be configured when creating a new
+repository. You can neither configure encryption on a per-archive
+basis, nor change the encryption mode of an existing repository. You
+should thus take possible future use into account when deciding on an
+encryption mode.
 
-Use ``repokey``::
+As a general rule of thumb, use ``repokey`` with a strong passphrase:
 
     borg init --encryption repokey /path/to/repo
 
-Or ``repokey-blake2`` depending on which is faster on your client machines (see below)::
-
-    borg init --encryption repokey-blake2 /path/to/repo
-
-Borg will:
+However, there are many reasons to choose differently. See the section
+below for details. In any case, Borg will:
+
+1. Ask you to enter a unique and strong passphrase.
+2. Create a random Borg key (which actually consists of three random
+   secrets, see :ref:`key_files` for details).
+3. Encrypt the Borg key with your passphrase.
+4. Store the encrypted Borg key inside the repository directory (with
+   ``repokey`` and ``repokey-blake2`` modes; with ``keyfile`` and
+   ``keyfile-blake2`` modes the Borg key is stored in your home
+   directory instead, see below). Since we usually have to assume that
+   an attacker could gain access to the repository (that's why we
+   encrypt the data in the first place), choosing a strong and unique
+   passphrase is absolutely crucial.
+5. Encrypt and sign your backups with the Borg key to prevent anyone
+   from reading or forging them unless they have the Borg key *and*
+   know the passphrase.
+6. Use the Borg key to decrypt and thus access the data stored in your
+   repository, e.g. when extracting files. The contents can also be
+   verified to detect accidental corruption or malicious tampering.
+
+As you can see, you always need *both* the Borg key and passphrase to
+access your data. Thus it's crucial to keep a backup of your key
+*outside* both the repository and the system you create backups of.
+You can easily run into a "leaving your keys inside your car" situation
+otherwise. See :ref:`borg_key_export` to create a backup of your key
+(e.g., by printing it on paper).
+
+Encryption is done locally - i.e., if you back up to a remote machine,
+the remote machine neither sees your passphrase, nor your unencrypted
+Borg key, nor your unencrypted files. Chunking and ID generation are
+based on your key to improve privacy.
+
+**About hardware acceleration:**
+
+Borg encrypts data with AES, which is pretty fast thanks to hardware
+acceleration on basically all modern Intel, AMD, and ARM CPUs since
+around the early 2010s (very cheap models since the mid-2010s).
+
+As the hashing algorithm, Borg can use either SHA256 or BLAKE2b. ARM
+CPUs support hardware-accelerated SHA256 hashing since ARMv7 with NEON
+(around 2011), or ARMv8 (around 2013). AMD CPUs support it since Zen 1
+(around 2017), i.e. all AMD Ryzen CPUs. Intel CPUs support it since Ice
+Lake on mobile (10th gen, around 2021), and Rocket Lake on desktop
+(11th gen, around 2021). Very cheap models have received support a few
+years later. If your CPU doesn't support hardware-accelerated SHA256
+hashing, you might want to give BLAKE2b hashing a try - it's likely
+faster then. So, instead of ``repokey`` mode, use ``repokey-blake2``
+(or any of the other ``-blake2`` modes for that matter).
 
-1. Ask you to come up with a passphrase.
-2. Create a borg key (which contains 3 random secrets. See :ref:`key_files`).
-3. Encrypt the key with your passphrase.
-4. Store the encrypted borg key inside the repository directory (in the repo config).
-   This is why it is essential to use a secure passphrase.
-5. Encrypt and sign your backups to prevent anyone from reading or forging them unless they
-   have the key and know the passphrase. Make sure to keep a backup of
-   your key **outside** the repository - do not lock yourself out by
-   "leaving your keys inside your car" (see :ref:`borg_key_export`).
-   For remote backups the encryption is done locally - the remote machine
-   never sees your passphrase, your unencrypted key or your unencrypted files.
-   Chunking and id generation are also based on your key to improve
-   your privacy.
-6. Use the key when extracting files to decrypt them and to verify that the contents of
-   the backups have not been accidentally or maliciously altered.
+Hardware acceleration is always used automatically when available.
 
 Picking a passphrase
 ++++++++++++++++++++
 
-Make sure you use a good passphrase. Not too short, not too simple. The real
-encryption / decryption key is encrypted with / locked by your passphrase.
-If an attacker gets your key, he can't unlock and use it without knowing the
-passphrase.
-
-Be careful with special or non-ascii characters in your passphrase:
-
-- Borg processes the passphrase as unicode (and encodes it as utf-8),
-  so it does not have problems dealing with even the strangest characters.
-- BUT: that does not necessarily apply to your OS / VM / keyboard configuration.
+Make sure you use a good passphrase. Not too short, not too simple. The
+real encryption / decryption key is encrypted with / locked by your
+passphrase. If an attacker gets your borg key, they can't unlock and use
+it without knowing the passphrase.
 
-So better use a long passphrase made from simple ascii chars than one that
-includes non-ascii stuff or characters that are hard/impossible to enter on
-a different keyboard layout.
+Be careful with special or non-ASCII characters in your passphrase:
 
-You can change your passphrase for existing repos at any time, it won't affect
-the encryption/decryption key or other secrets.
+- Borg processes the passphrase as Unicode (and encodes it as UTF-8), so
+  it does not have problems dealing with even the strangest characters.
+- BUT: that does not necessarily apply to your OS / VM / keyboard
+  configuration.
 
-More encryption modes
-+++++++++++++++++++++
+So it is better to use a long passphrase made from simple ASCII
+characters than one that includes non-ASCII characters or characters
+that are hard or impossible to enter on a different keyboard layout.
 
-Only use ``--encryption none`` if you are OK with anyone who has access to
-your repository being able to read your backups and tamper with their
-contents without you noticing.
+You can change your passphrase for existing repositories at any time; it
+won't affect the encryption/decryption key or other secrets. See
+:ref:`borg_key_change-passphrase`.
 
-If you want "passphrase and having-the-key" security, use ``--encryption keyfile``.
-The key will be stored in your home directory (in ``~/.config/borg/keys``).
+More about encryption modes
++++++++++++++++++++++++++++
 
-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.
+Choosing the right encryption mode isn't always easy and many factors
+can change which mode is best for you. However, note that you can't
+really do anything *wrong* if you choose ``repokey`` with a strong
+passphrase. So, if you're not sure, choose ``repokey`` (or
+``repokey-blake2``, depending on your hardware, see above).
 
-If ``BLAKE2b`` is faster than ``SHA-256`` on your hardware, use ``--encryption authenticated-blake2``,
-``--encryption repokey-blake2`` or ``--encryption keyfile-blake2``. Note: for remote backups
-the hashing is done on your local machine.
+Borg supports the following encryption modes:
 
 .. nanorst: inline-fill
-
-+----------+---------------+------------------------+--------------------------+
-| Hash/MAC | Not encrypted | Not encrypted,         | Encrypted (AEAD w/ AES)  |
-|          | no auth       | but authenticated      | and authenticated        |
-+----------+---------------+------------------------+--------------------------+
-| SHA-256  | none          | `authenticated`        | repokey                  |
-|          |               |                        | keyfile                  |
-+----------+---------------+------------------------+--------------------------+
-| BLAKE2b  | n/a           | `authenticated-blake2` | `repokey-blake2`         |
-|          |               |                        | `keyfile-blake2`         |
-+----------+---------------+------------------------+--------------------------+
+.. class:: borg-encryption-table
+
++----------+-------------------+--------------------------+-------------------------+
+| Hash/MAC | Not Encrypted                                | Encrypted (AEAD w/ AES) |
++          +-------------------+--------------------------+-------------------------+
+|          | Not Authenticated | Authenticated                                      |
++==========+===================+==========================+=========================+
+| SHA-256  | ``none``          | ``authenticated``        | ``repokey``             |
+|          |                   |                          | ``keyfile``             |
++----------+-------------------+--------------------------+-------------------------+
+| BLAKE2b  | n/a               | ``authenticated-blake2`` | ``repokey-blake2``      |
+|          |                   |                          | ``keyfile-blake2``      |
++----------+-------------------+--------------------------+-------------------------+
 
 .. nanorst: inline-replace
 
-Modes `marked like this` in the above table are new in Borg 1.1 and are not
-backwards-compatible with Borg 1.0.x.
-
-On modern Intel/AMD CPUs (except very cheap ones), AES is usually
-hardware-accelerated.
-BLAKE2b is faster than SHA256 on Intel/AMD 64-bit CPUs
-(except AMD Ryzen and future CPUs with SHA extensions),
-which makes `authenticated-blake2` faster than `none` and `authenticated`.
-
-On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
-than BLAKE2b-256 there. NEON accelerates AES as well.
-
-Hardware acceleration is always used automatically when available.
-
-`repokey` and `keyfile` use AES-CTR-256 for encryption and HMAC-SHA256 for
-authentication in an encrypt-then-MAC (EtM) construction. The chunk ID hash
-is HMAC-SHA256 as well (with a separate key).
-These modes are compatible with Borg 1.0.x.
-
-`repokey-blake2` and `keyfile-blake2` are also authenticated encryption modes,
-but use BLAKE2b-256 instead of HMAC-SHA256 for authentication. The chunk ID
-hash is a keyed BLAKE2b-256 hash.
-These modes are new and *not* compatible with Borg 1.0.x.
-
-`authenticated` mode uses no encryption, but authenticates repository contents
-through the same HMAC-SHA256 hash as the `repokey` and `keyfile` modes (it uses it
-as the chunk ID hash). The key is stored like `repokey`.
-This mode is new and *not* compatible with Borg 1.0.x.
-
-`authenticated-blake2` is like `authenticated`, but uses the keyed BLAKE2b-256 hash
-from the other blake2 modes.
-This mode is new and *not* compatible with Borg 1.0.x.
-
-`none` mode uses no encryption and no authentication. It uses SHA256 as chunk
-ID hash. This mode is not recommended, you should rather consider using an authenticated
-or authenticated/encrypted mode. This mode has possible denial-of-service issues
-when running ``borg create`` on contents controlled by an attacker.
-Use it only for new repositories where no encryption is wanted **and** when compatibility
-with 1.0.x is important. If compatibility with 1.0.x is not important, use
-`authenticated-blake2` or `authenticated` instead.
-This mode is compatible with Borg 1.0.x.
+Borg 1.0 and older support ``none``, ``repokey``, and ``keyfile``
+modes only. If you need such old clients to be able to access your
+repo, you can't use any of the other modes.
+
+**About modes without encryption:**
+
+Avoid using ``none`` mode. If you think about using ``none`` mode,
+please reconsider and be absolutely sure. Using any mode other than
+``none`` allows Borg to detect accidental corruption or malicious
+tampering with the repo. It also prevents denial-of-service attacks
+against clients. Instead of ``none`` mode, you likely want to use
+``authenticated`` mode, or ``repokey`` or ``keyfile`` modes with an
+empty passphrase instead (see below).
+
+If you don't want to encrypt your data, use ``authenticated`` or
+``authenticated-blake2`` modes. These modes require a passphrase in
+normal operation, but in emergency situations you can access the repo
+without the passphrase with ``BORG_WORKAROUNDS=authenticated_no_key``
+(see :ref:`environment-variables`).
+
+If you just don't want to choose a passphrase, use ``keyfile`` or
+``keyfile-blake2`` modes with an empty passphrase. These modes are
+generally safe even without a passphrase, but keeping an offsite
+backup of the Borg key is also important then. See below for details.
+
+If you can assure that an attacker can't gain access to your repo, e.g.
+when independently encrypting your repository disk or filesystem, you
+can think about using ``repokey`` or ``repokey-blake2`` modes with an
+empty passphrase. However, keep in mind that if an attacker still
+somehow manages to gain access, they have full access to your repo. In
+such situations choosing ``repokey`` over ``authenticated`` mode has
+the advantage of allowing you to add a passphrase later using
+:ref:`borg_key_change-passphrase`.
+
+**About modes with encryption:**
+
+With ``repokey`` and ``repokey-blake2`` modes the key is stored with
+the repo and encrypted with your passphrase. If an attacker gains
+access to your repo and knows the passphrase, he can access and tamper
+with the repo. The repo's security thus relies on the strength of your
+passphrase. Creating an offsite backup of your Borg key (e.g., by
+printing it on paper) is recommended, see :ref:`borg_key_export`.
+
+If you're thinking about storing the passphrase on the disk of the
+system you're backing up, consider using the ``keyfile`` method
+instead. It generally provides the same or better security then.
+
+With ``keyfile`` and ``keyfile-blake2`` modes the key is stored on your
+local machine (in ``~/.config/borg/keys``) instead. An attacker gaining
+access to your repo then needs both the Borg key, and your passphrase to
+access and tamper with the repo. However, if you lose the key, you lose
+access to the repo, too. You **must** create an offsite backup of your
+Borg key, e.g. by printing it on paper. Storing a copy of the Borg key
+on the system you're creating backups of is **NOT** sufficient. Use
+:ref:`borg_key_export` to create the backup.
+
+The ``keyfile`` and ``keyfile-blake2`` modes allow for "passphrase and
+having-the-key" security when using a strong passphrase, but can also
+be used with an empty passphrase. Storing a (easily readable)
+passphrase on the disk of the system you're backing up with
+``keyfile`` and ``keyfile-blake2`` modes adds no security over using an
+empty passphrase.
+
+**Technical details:**
+
+``repokey`` and ``keyfile`` use AES-CTR-256 for encryption and
+HMAC-SHA256 for authentication in an encrypt-then-MAC (EtM)
+construction. The chunk ID hash is HMAC-SHA256 (with a separate key).
+These modes are compatible with all Borg versions.
+
+``repokey-blake2`` and ``keyfile-blake2`` are also authenticated
+encryption modes, but use BLAKE2b-256 instead of HMAC-SHA256 for
+authentication. The chunk ID hash is a keyed BLAKE2b-256 hash. These
+modes are only compatible with Borg 1.1 and later.
+
+``authenticated`` mode uses no encryption, but authenticates repo
+contents through the same HMAC-SHA256 hash as the ``repokey`` and
+``keyfile`` modes (it uses it as the chunk ID hash). The key is stored
+like ``repokey`` within the repo. This mode is only compatible with
+Borg 1.1 and later.
+
+``authenticated-blake2`` is like ``authenticated``, but uses the keyed
+BLAKE2b-256 hash from the other BLAKE2b modes. This mode is only
+compatible with Borg 1.1 and later.
+
+``none`` mode uses no encryption and no authentication. It uses SHA256
+as chunk ID hash. This mode is not recommended. You should instead
+consider using an authenticated or authenticated/encrypted mode. This
+mode has possible denial-of-service issues when running ``borg create``
+on contents controlled by an attacker. See above for alternatives.
+This mode is compatible with all Borg versions.

docs/usage/key_change-passphrase.rst.inc

@@ -42,10 +42,10 @@ borg key change-passphrase
 Description
 ~~~~~~~~~~~
 
-The key files used for repository encryption are optionally passphrase
+The key files used for repository encryption are optionally passphrase-
 protected. This command can be used to change this passphrase.
 
 Please note that this command only changes the passphrase, but not any
-secret protected by it (like e.g. encryption/MAC keys or chunker seed).
-Thus, changing the passphrase after passphrase and borg key got compromised
+secret protected by it (e.g., encryption/MAC keys or the chunker seed).
+Thus, changing the passphrase after the passphrase and Borg key were compromised
 does not protect future (nor past) backups to the same repository.

docs/usage/key_export.rst.inc

@@ -58,15 +58,15 @@ Description
 ~~~~~~~~~~~
 
 If repository encryption is used, the repository is inaccessible
-without the key. This command allows one to backup this essential key.
+without the key. This command allows one to back up this essential key.
 Note that the backup produced does not include the passphrase itself
-(i.e. the exported key stays encrypted). In order to regain access to a
+(i.e., the exported key stays encrypted). In order to regain access to a
 repository, one needs both the exported key and the original passphrase.
 
 There are three backup formats. The normal backup format is suitable for
 digital storage as a file. The ``--paper`` backup format is optimized
-for printing and typing in while importing, with per line checks to
-reduce problems with manual input. The ``--qr-html`` creates a printable
+for printing and typing in while importing, with per-line checks to
+reduce problems with manual input. The ``--qr-html`` option creates a printable
 HTML template with a QR code and a copy of the ``--paper``-formatted key.
 
 For repositories using keyfile encryption the key is saved locally
@@ -74,9 +74,9 @@ on the system that is capable of doing backups. To guard against loss
 of this key, the key needs to be backed up independently of the main
 data backup.
 
-For repositories using the repokey encryption the key is saved in the
+For repositories using repokey encryption, the key is saved in the
 repository in the config file. A backup is thus not strictly needed,
-but guards against the repository becoming inaccessible if the file
+but it guards against the repository becoming inaccessible if the file
 is damaged for some reason.
 
 Examples::

docs/usage/key_import.rst.inc

@@ -58,12 +58,12 @@ This command restores a key previously backed up with the export command.
 
 If the ``--paper`` option is given, the import will be an interactive
 process in which each line is checked for plausibility before
-proceeding to the next line. For this format PATH must not be given.
+proceeding to the next line. For this format, PATH must not be provided.
 
 For repositories using keyfile encryption, the key file which ``borg key
 import`` writes to depends on several factors. If the ``BORG_KEY_FILE``
 environment variable is set and non-empty, ``borg key import`` creates
-or overwrites that file named by ``$BORG_KEY_FILE``. Otherwise, ``borg
+or overwrites the file named by ``$BORG_KEY_FILE``. Otherwise, ``borg
 key import`` searches in the ``$BORG_KEYS_DIR`` directory for a key file
 associated with the repository. If a key file is found in
 ``$BORG_KEYS_DIR``, ``borg key import`` overwrites it; otherwise, ``borg

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

@@ -45,10 +45,10 @@ Description
 This command migrates a repository from passphrase mode (removed in Borg 1.0)
 to repokey mode.
 
-You will be first asked for the repository passphrase (to open it in passphrase
-mode). This is the same passphrase as you used to use for this repo before 1.0.
+You will first be asked for the repository passphrase (to open it in passphrase
+mode). This is the same passphrase you used for this repository before 1.0.
 
-It will then derive the different secrets from this passphrase.
+The different secrets will then be derived from this passphrase.
 
 Then you will be asked for a new passphrase (twice, for safety). This
 passphrase will be used to protect the repokey (which contains these same
@@ -56,5 +56,5 @@ secrets in encrypted form). You may use the same passphrase as you used to
 use, but you may also use a different one.
 
 After migrating to repokey mode, you can change the passphrase at any time.
-But please note: the secrets will always stay the same and they could always
+Please note: the secrets will always stay the same, and they could always
 be derived from your (old) passphrase-mode passphrase.

docs/usage/list.rst.inc

@@ -112,7 +112,7 @@ For more help on include/exclude patterns, see the :ref:`borg_patterns` command
 The FORMAT specifier syntax
 +++++++++++++++++++++++++++
 
-The ``--format`` option uses python's `format string syntax
+The ``--format`` option uses Python's `format string syntax
 <https://docs.python.org/3.9/library/string.html#formatstrings>`_.
 
 Examples:

docs/usage/mount.rst.inc

@@ -114,19 +114,19 @@ This command mounts a repository or an archive as a FUSE filesystem.
 This can be useful for browsing or restoring individual files.
 
 When restoring, take into account that the current FUSE implementation does
-not support special fs flags and ACLs.
+not support special filesystem flags and ACLs.
 
 When mounting a repository, the top directories will be named like the
 archives and the directory structure below these will be loaded on-demand from
 the repository when entering these directories, so expect some delay.
 
 Unless the ``--foreground`` option is given the command will run in the
-background until the filesystem is ``umounted``.
+background until the filesystem is ``unmounted``.
 
 Performance tips:
 
 - when doing a "whole repository" mount:
-  do not enter archive dirs if not needed, this avoids on-demand loading.
+  do not enter archive directories if not needed; this avoids on-demand loading.
 - only mount a specific archive, not the whole repository.
 - only mount specific paths in a specific archive, not the complete archive.
 
@@ -149,7 +149,7 @@ override the user and group ids of all files (i.e., ``borg mount -o
 uid=1000,gid=1000``).
 
 The man page references ``user_id`` and ``group_id`` mount options
-(implemented by fuse) which specify the user and group id of the mount owner
+(implemented by FUSE) which specify the user and group id of the mount owner
 (aka, the user who does the mounting). It is set automatically by libfuse (or
 the filesystem if libfuse is not used). However, you should not specify these
 manually. Unlike the ``uid`` and ``gid`` mount options which affect all files,
@@ -159,7 +159,7 @@ manually. Unlike the ``uid`` and ``gid`` mount options which affect all files,
 Additional mount options supported by borg:
 
 - ``versions``: when used with a repository mount, this gives a merged, versioned
-  view of the files in the archives. EXPERIMENTAL, layout may change in future.
+  view of the files in the archives. EXPERIMENTAL; the layout may change in the future.
 - ``allow_damaged_files``: by default damaged files (where missing chunks were
   replaced with runs of zeros by ``borg check --repair``) are not readable and
   return EIO (I/O error). Set this option to read such files.
@@ -177,4 +177,11 @@ Unmounting in these cases could cause an active rsync or similar process
 to unintentionally delete data.
 
 When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
-but other signals or crashes do not.
+but other signals or crashes do not.
+
+Debugging:
+
+``borg mount`` usually daemonizes and the daemon process sends stdout/stderr
+to /dev/null. Thus, you need to either use ``-f / --foreground`` to make it stay
+in the foreground and not daemonize, or use ``BORG_LOGGING_CONF`` to reconfigure
+the logger to output to a file.

docs/usage/prune.rst.inc

@@ -144,9 +144,9 @@ up to 7 most recent days with backups (days without backups do not count).
 The rules are applied from secondly to yearly, and backups selected by previous
 rules do not count towards those of later rules. The time that each backup
 starts is used for pruning purposes. Dates and times are interpreted in
-the local timezone, and weeks go from Monday to Sunday. Specifying a
-negative number of archives to keep means that there is no limit. As of borg
-1.2.0, borg will retain the oldest archive if any of the secondly, minutely,
+the local time zone, and weeks go from Monday to Sunday. Specifying a
+negative number of archives to keep means that there is no limit. As of Borg
+1.2.0, Borg will retain the oldest archive if any of the secondly, minutely,
 hourly, daily, weekly, monthly, quarterly, 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

docs/usage/recreate.rst.inc

@@ -117,7 +117,7 @@ Description
 
 Recreate the contents of existing archives.
 
-recreate is a potentially dangerous function and might lead to data loss
+Recreate is a potentially dangerous operation and might lead to data loss
 (if used wrongly). BE VERY CAREFUL!
 
 Important: Repository disk space is **not** freed until you run ``borg compact``.
@@ -135,33 +135,33 @@ Due to how Borg stores compressed size information this might display
 incorrect information for archives that were not recreated at the same time.
 There is no risk of data loss by this.
 
-``--chunker-params`` will re-chunk all files in the archive, this can be
+``--chunker-params`` will re-chunk all files in the archive; this can be
 used to have upgraded Borg 0.xx or Attic archives deduplicate with
 Borg 1.x archives.
 
 **USE WITH CAUTION.**
 Depending on the PATHs and patterns given, recreate can be used to permanently
 delete files from archives.
-When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are
+When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHs are
 interpreted. See :ref:`list_item_flags` in ``borg create`` for details.
 
 The archive being recreated is only removed after the operation completes. The
 archive that is built during the operation exists at the same time at
 "<ARCHIVE>.recreate". The new archive will have a different archive ID.
 
-With ``--target`` the original archive is not replaced, instead a new archive is created.
+With ``--target`` the original archive is not replaced; instead, a new archive is created.
 
 When rechunking (or recompressing), space usage can be substantial - expect
 at least the entire deduplicated size of the archives using the previous
-chunker (or compression) params.
+chunker (or compression) parameters.
 
-If you recently ran borg check --repair and it had to fix lost chunks with all-zero
+If you recently ran ``borg check --repair`` and it had to fix lost chunks with all-zero
 replacement chunks, please first run another backup for the same data and re-run
-borg check --repair afterwards to heal any archives that had lost chunks which are
+``borg check --repair`` afterwards to heal any archives that had lost chunks which are
 still generated from the input data.
 
-Important: running borg recreate to re-chunk will remove the chunks_healthy
+Important: running ``borg recreate`` to re-chunk will remove the ``chunks_healthy``
 metadata of all items with replacement chunks, so healing will not be possible
-any more after re-chunking (it is also unlikely it would ever work: due to the
+anymore after re-chunking (it is also unlikely it would ever work: due to the
 change of chunking parameters, the missing chunk likely will never be seen again
 even if you still have the data that produced it).

docs/usage/umount.rst.inc

@@ -42,7 +42,7 @@ borg umount
 Description
 ~~~~~~~~~~~
 
-This command un-mounts a FUSE filesystem that was mounted with ``borg mount``.
+This command unmounts a FUSE filesystem that was mounted with ``borg mount``.
 
 This is a convenience wrapper that just calls the platform-specific shell
 command - usually this is either umount or fusermount -u.

docs/usage/upgrade.rst.inc

@@ -96,8 +96,8 @@ archives that are not TAM authenticated yet.
 This is a convenient method to just trust all archives present - if
 an archive does not have TAM authentication yet, a TAM will be added.
 Archives created by old borg versions < 1.0.9 do not have TAMs.
-Archives created by newer borg version should have TAMs already.
-If you have a high risk environment, you should not just run this,
+Archives created by newer borg versions should have TAMs already.
+If you have a high-risk environment, you should not just run this,
 but first verify that the archives are authentic and not malicious
 (== have good content, have a good timestamp).
 Borg 1.2.5+ needs all archives to be TAM authenticated for safety reasons.
@@ -139,7 +139,7 @@ with the old chunks in the upgraded repository.
 See ``--chunker-params`` option of ``borg create`` and ``borg recreate``.
 
 ``borg upgrade`` will change the magic strings in the repository's
-segments to match the new Borg magic strings. The keyfiles found in
+segments to match the new Borg magic strings. The key files found in
 $ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
 copied to $BORG_KEYS_DIR or ~/.config/borg/keys.
 
@@ -147,11 +147,11 @@ The cache files are converted, from $ATTIC_CACHE_DIR or
 ~/.cache/attic to $BORG_CACHE_DIR or ~/.cache/borg, but the
 cache layout between Borg and Attic changed, so it is possible
 the first backup after the conversion takes longer than expected
-due to the cache resync.
+due to the cache re-sync.
 
 Upgrade should be able to resume if interrupted, although it
 will still iterate over all segments. If you want to start
-from scratch, use `borg delete` over the copied repository to
+from scratch, use ``borg delete`` over the copied repository to
 make sure the cache files are also removed::
 
     borg delete borg

docs/usage/version.rst.inc

@@ -42,12 +42,12 @@ borg version
 Description
 ~~~~~~~~~~~
 
-This command displays the borg client version / borg server version.
+This command displays the Borg client version / Borg server version.
 
-If a local repo is given, the client code directly accesses the repository,
+If a local repository is given, the client code directly accesses the repository,
 thus we show the client version also as the server version.
 
-If a remote repo is given (e.g. ssh:), the remote borg is queried and
+If a remote repository is given (e.g., ssh:), the remote Borg is queried and
 its version is displayed as the server version.
 
 Examples::
@@ -60,7 +60,7 @@ Examples::
     $ borg version ssh://borg@borgbackup:repo
     1.4.0a / 1.2.7
 
-Due to the version tuple format used in borg client/server negotiation, only
-a simplified version is displayed (as provided by borg.version.format_version).
+Due to the version tuple format used in Borg client/server negotiation, only
+a simplified version is displayed (as provided by ``borg.version.format_version``).
 
-There is also borg --version to display a potentially more precise client version.
+There is also ``borg --version`` to display a potentially more precise client version.

docs/usage/with-lock.rst.inc

@@ -57,13 +57,13 @@ This command runs a user-specified command while locking the repository. For exa
     $ borg with-lock /mnt/borgrepo rsync -av /mnt/borgrepo /somewhere/else/borgrepo
 
 It will first try to acquire the lock (make sure that no other operation is
-running in the repo), then execute the given command as a subprocess and wait
-for its termination, release the lock and return the user command's return
-code as borg's return code.
+running in the repository), then execute the given command as a subprocess and wait
+for its termination, release the lock, and return the user command's return
+code as Borg's return code.
 
 .. note::
 
     If you copy a repository with the lock held, the lock will be present in
-    the copy. Thus, before using borg on the copy from a different host,
+    the copy. Thus, before using Borg on the copy from a different host,
     you need to use "borg break-lock" on the copied repository, because
     Borg is cautious and does not automatically remove stale locks made by a different host.