Release 2.0.0b25

docs/changes.rst

@@ -163,8 +163,8 @@ Compatibility notes:
 Change Log 2.x
 ==============
 
-Version 2.0.0b25 (not released yet)
------------------------------------
+Version 2.0.0b25 (2026-09-27)
+-----------------------------
 
 Breaking changes (you must create new repos for b25):
 

docs/man/borg-analyze.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-analyze" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-analyze" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-analyze \- Analyzes archives.
 .SH SYNOPSIS

docs/man/borg-benchmark-cpu.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-benchmark-cpu" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-benchmark-cpu" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-benchmark-cpu \- Benchmark CPU-bound operations.
 .SH SYNOPSIS

docs/man/borg-benchmark-crud.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-benchmark-crud" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-benchmark-crud" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .SH SYNOPSIS

docs/man/borg-benchmark.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-benchmark" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-benchmark" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-benchmark \- benchmark command
 .SH SYNOPSIS

docs/man/borg-break-lock.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-break-lock" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-break-lock" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-break-lock \- Breaks the repository lock (for example, if it was left by a dead Borg process).
 .SH SYNOPSIS
@@ -39,6 +39,9 @@ borg [common options] break\-lock [options]
 This command breaks the repository and cache locks.
 Use with care and only when no Borg process (on any machine) is
 trying to access the cache or the repository.
+.sp
+The repository lock objects are protected by the repository key, so this
+command needs the key.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

docs/man/borg-check.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-check" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-check" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-check \- Checks repository consistency.
 .SH SYNOPSIS
@@ -41,15 +41,20 @@ It consists of two major steps:
 .INDENT 0.0
 .IP 1. 3
 Checking the consistency of the repository itself. The objects in the \fBindex/\fP
-and \fBpacks/\fP namespaces are named by the sha256 hash of their content, so such
+and \fBpacks/\fP namespaces are named by the store hash of their content, so such
 an object is intact if and only if the hash of its content still equals its name.
 The check verifies the (small) index objects first and, only if they are intact,
 all packs. It also cross\-checks the chunk index against the packs present in the
 repository to detect referenced but missing packs. Bit rot and other types of
-accidental damage can be detected this way, but as sha256 content\-addressing is
-not a MAC, this step does not detect tampering. Running the repository check can
+accidental damage can be detected this way, but as content\-addressing is
+not a MAC, this step does not detect tampering of the packs. The index objects
+are also authenticated with the key when they are loaded for that cross\-check.
+A corrupt index ends the check after this step, as the archives check needs it,
+unless \fB\-\-repair\fP is given (see below). This step also verifies the repository
+defaults object (see \fBborg repo\-create\fP): it must be present and authenticate
+with the key. Running the repository check can
 be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
-For rest:// repositories, the server computes the hashes, so the pack contents do
+For \%<ssh://> repositories, the server computes the hashes, so the pack contents do
 not have to travel over the network. For other remote backends, borg usually has
 to read (download) the objects to hash them.
 .IP 2. 3
@@ -73,6 +78,10 @@ Both steps can also be run independently. Pass \fB\-\-repository\-only\fP to run
 repository checks only, or pass \fB\-\-archives\-only\fP to run the archive checks
 only.
 .sp
+\fBborg check\fP always needs the key, \fB\-\-repository\-only\fP included: it loads
+the key (asking for the passphrase, if needed) before it checks anything and
+aborts if the key can not be loaded.
+.sp
 The \fB\-\-max\-age\fP option makes the check reuse the results of previous
 repository checks: packs whose intact result is younger than the given
 timespan (e.g. \fB\-\-max\-age=4w\fP or \fB\-\-max\-age=12m\fP) are skipped, spreading
@@ -132,16 +141,18 @@ description for more details about the format string).
 If the \fBborg check\fP process receives a SIGINT signal (Ctrl\-C), it stops at the
 next safe boundary, leaving the repository and its chunk index in a consistent state.
 The repository check stops after the current pack; \fB\-\-verify\-data\fP and
-\fB\-\-find\-lost\-archives\fP stop after the current chunk; a \fB\-\-repair\fP archive check
-stops between whole archives. Results recorded before the interrupt are kept, so a later
-check does not re\-verify those packs until they are due again. With \fB\-\-repair\fP, an
-interrupted archive check may leave some archives already repaired and others not yet
-processed, so run \fBborg check \-\-repair\fP again to finish.
-.sp
-During a \fB\-\-repair\fP run, the archive check first rebuilds the chunk index from the
-packs, and, if the key must be recovered, scans chunks for it. These phases do not yet
-respond to SIGINT, so on a large repository a Ctrl\-C during them may appear to have no
-effect until they finish.
+\fB\-\-find\-lost\-archives\fP stop after the current chunk; the archive check stops after the
+current archive item, with \fB\-\-repair\fP between whole archives. Results recorded before
+the interrupt are kept, so a later check does not re\-verify those packs until they are
+due again. With \fB\-\-repair\fP, an interrupted archive check may leave some archives already
+repaired and others not yet processed, so run \fBborg check \-\-repair\fP again to finish.
+.sp
+\fBborg check\fP rebuilds the chunk index from the packs when \fB\-\-repair\fP is given or when
+the stored index cannot be used. Ctrl\-C stops that rebuild after the current object and
+discards the partial index: it lacks chunks that are still in the repository, so the check
+would report them as lost. After a \fB\-\-repair\fP that stored or deleted chunks, borg re\-reads the
+packs the repair wrote, makes the chunk index match them and stores it; that always runs to
+completion, also after a Ctrl\-C.
 .SS About repair mode
 .sp
 The check command is a read\-only task by default. If any corruption is found,
@@ -176,10 +187,17 @@ In practice, repair mode hooks into both the repository and archive checks:
 .INDENT 0.0
 .IP 1. 3
 When checking the repository\(aqs consistency, repair mode rebuilds the repository
-index from the packs if the index is corrupt, provided every pack is intact. If
-any pack is corrupt, the repository check leaves the index and the packs untouched
-and reports the corruption; salvaging a corrupt pack\(aqs still\-intact objects is not
-implemented yet (refs #8572).
+index from the packs if the index is corrupt, provided every pack matches its
+store hash. If any pack fails its store hash, the repository check leaves the
+index and the packs untouched and reports it; salvaging the intact objects of
+such a pack is not implemented yet (refs #8572). The rebuild authenticates
+each object\(aqs header and metadata with the key, leaves an object that fails
+this out of the index and reports it as an error. Repair mode also removes the
+index entries of the chunks stored in missing packs (packs the index references,
+but that are absent from the repository). Only a full \fBborg check \-\-repair\fP
+repairs the archives that reference these chunks, \fB\-\-repository\-only\fP does not.
+A missing or corrupt repository defaults object is replaced by empty defaults, so
+the repository can be used again; the commands then use the built\-in defaults.
 .IP 2. 3
 When checking the consistency and correctness of archives, repair mode might
 remove whole archives from the manifest if their archive metadata chunk is

docs/man/borg-common.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-common" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-common" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-common \- Common options of Borg commands
 .SH SYNOPSIS

docs/man/borg-compact.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-compact" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-compact" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-compact \- Collects garbage in the repository.
 .SH SYNOPSIS
@@ -60,6 +60,13 @@ Other bytes no index entry covers, such as packs left behind by a backup that cr
 before recording its objects, are re\-indexed by \fBborg check \-\-repair\fP and reclaimed by
 the next \fBborg compact\fP\&.
 .sp
+\fBborg compact\fP does not rewrite or merge packs that \fBborg check\fP recorded as corrupt
+and warns about them. \fBborg check \-\-repair \-\-verify\-data\fP deletes the corrupt chunks by
+rewriting their packs. It does not remove damage outside any chunk (e.g. bytes appended to a
+pack): a pack with such damage and no corrupt chunk stays recorded corrupt and \fBborg compact\fP
+warns about it on every run, a pack that also has a corrupt chunk is rewritten with that damage
+copied into the new pack (refs #10026).
+.sp
 You usually do not want to run \fBborg compact\fP after every write operation, but
 either regularly (e.g., once a month, possibly together with \fBborg check\fP) or
 when disk space needs to be freed.

docs/man/borg-completion.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-completion" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-completion" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-completion \- Output shell completion script for the given shell.
 .SH SYNOPSIS

docs/man/borg-compression.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-compression" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-compression" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-compression \- Details regarding compression
 .SH DESCRIPTION
@@ -42,7 +42,9 @@ another backup that also uses this chunk will not change the stored chunk.
 So if you use different compression specs for the backups, whichever stores a
 chunk first determines its compression. See also \fBborg recreate\fP\&.
 .sp
-Compression is lz4 by default. If you want something else, you have to specify what you want.
+If you do not specify a compression via \fB\-\-compression\fP (or the environment or the
+default config file), the repository\(aqs default compression is used, which can be set
+with \fBborg repo\-create \-\-compression\fP\&. Without a repository default, compression is lz4.
 .sp
 Valid compression specifiers are:
 .INDENT 0.0
@@ -51,7 +53,7 @@ Valid compression specifiers are:
 Do not compress.
 .TP
 .B lz4
-Use lz4 compression. Very high speed, very low compression. (default)
+Use lz4 compression. Very high speed, very low compression. (built\-in default)
 .TP
 .B zstd[,L]
 Use zstd (\(dqzstandard\(dq) compression, a modern wide\-range algorithm.

docs/man/borg-copy.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-copy" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-copy" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-copy \- Copy an archive to a new archive name.
 .SH SYNOPSIS

docs/man/borg-create.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-create" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-create" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-create \- Creates a new archive.
 .SH SYNOPSIS
@@ -71,7 +71,8 @@ appropriate to use \-\-content\-from\-command. See the section
 The archive will consume almost no disk space for files or parts of files that
 have already been stored in other archives.
 .sp
-The \fB\-\-tags\fP option can be used to add a list of tags to the new archive.
+The \fB\-\-tag\fP option can be used to add a tag to the new archive. To add
+multiple tags, give it multiple times, e.g. \fB\-\-tag foo \-\-tag bar\fP\&.
 .sp
 The archive name does not need to be unique; you can and should use the same
 name for a series of archives. The unique archive identifier is its ID (hash),
@@ -179,9 +180,8 @@ terminals, the compact format is used, so that the path stays readable. If the o
 does not go to a terminal (e.g. into a logfile), the precise format is always used.
 .sp
 When using \fB\-\-stats\fP, you will get some statistics about how much data was
-added \- the \(dqThis Archive\(dq deduplicated size there is most interesting as that is
-how much your repository will grow. Please note that the \(dqAll archives\(dq stats refer to
-the state after creation.
+added \- the deduplicated size there is most interesting as that is how much your
+repository will grow. \fB\-\-json\fP outputs the same statistics as JSON.
 .sp
 When \fB\-\-stats\fP is used together with \fB\-\-dry\-run\fP, only the number of files and the
 original size are reported. They are computed from file system metadata, without reading
@@ -361,13 +361,13 @@ add a comment text to the archive
 manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH:MM] format, (+|\-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
 .TP
 .BI \-\-chunker\-params \ PARAMS
-specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: fastcdc,19,23,21,2
+specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: the repository default (see borg repo\-create), else fastcdc,19,23,21,2
 .TP
 .BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
-select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
+select compression algorithm, see the output of the \(dqborg help compression\(dq command for details. Default: the repository default (see borg repo\-create), else lz4.
 .TP
-.BI \-\-tags \ TAG
-add tags to archive (comma\-separated or multiple arguments)
+.BI \-\-tag \ TAG
+add tag to archive (can be given multiple times)
 .UNINDENT
 .SH EXAMPLES
 .sp

docs/man/borg-delete.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-delete" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-delete" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-delete \- Deletes archives.
 .SH SYNOPSIS

docs/man/borg-diff.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-diff" "1" "2026-09-02" "" "borg backup tool"
+.TH "borg-diff" "1" "2026-09-27" "" "borg backup tool"
 .SH Name
 borg-diff \- Finds differences between two archives.
 .SH SYNOPSIS
@@ -69,6 +69,9 @@ specify format for differences between archives (default: \(dq{change} {path}{NL
 .B  \-\-json\-lines
 Format output as JSON Lines.
 .TP
+.B  \-s\fP,\fB  \-\-stats
+print a summary of the differences at the end
+.TP
 .B  \-\-sort\-by
 Sort output by comma\-separated fields (e.g., \(aq>size_added,path\(aq).
 .TP
@@ -212,9 +215,15 @@ 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. In the latter case, borg
-can only tell that a file was modified, not by how much: no byte counts are given for it, the
-text output shows \(dqmodified:  (can\(aqt get size)\(dq instead.
+Borg compares chunk IDs quickly: it aligns the two chunk lists of a file like a text diff
+aligns lines, and the byte counts are the total sizes of the chunks that are not part of that
+alignment. Inserted, removed, moved and duplicated content is therefore accounted for \- a
+chunk that only moved within the file shows up as removed and added again. Files with very
+long or very repetitive chunk lists are not aligned (this would be too slow); for these, only
+the number of occurrences of each chunk ID is compared, so moved content does not show up in
+their byte counts. If chunker parameters are not comparable, Borg compares the content. In
+that case, borg can only tell that a file was modified, not by how much: no byte counts
+are given for it, the text output shows \(dqmodified:  (can\(aqt get size)\(dq instead.
 .IP \(bu 2
 Metadata changes: user, group, mode, and other metadata shown inline as \(dq[old \-> new]\(dq, like
 \(dq[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x]\(dq for a mode change. Use \fB\-\-content\-only\fP to suppress metadata changes.
@@ -253,6 +262,41 @@ values as \(dqitem1\(dq and \(dqitem2\(dq. Example:
 .EE
 .UNINDENT
 .UNINDENT
+.SS Statistics
+.sp
+With \fB\-\-stats\fP, borg prints a summary of the differences after the per\-path output:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+Added items: 23
+Removed items: 2
+Changed items: 315
+Added size: 53.70 MB
+Removed size: 51.10 MB
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+\(dqAdded\(dq/\(dqRemoved\(dq items only exist in ARCHIVE2/ARCHIVE1, \(dqchanged\(dq items exist in both
+archives but differ. \(dqAdded size\(dq/\(dqRemoved size\(dq sum up the file content (in bytes) added/removed
+by all of these items, i.e. the per\-path byte counts that \fB\-\-sort\-by size_added\fP /
+\fBsize_removed\fP sort by. Items whose content borg could only
+compare byte by byte (see \(dqPerformance considerations\(dq below) contribute no byte counts;
+if there are any, an additional \(dqItems with unknown size changes\(dq line reports how many.
+.sp
+Together with \fB\-\-json\-lines\fP, the summary is emitted as a final JSON line of the shape
+\fB{\(dqstats\(dq: {...}}\fP instead, so it is easy to tell apart from the per\-path lines
+(wrapped here for readability, borg prints it as a single line):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+{\(dqstats\(dq: {\(dqadded_items\(dq: 23, \(dqchanged_items\(dq: 315, \(dqremoved_items\(dq: 2,
+           \(dqsize_added\(dq: 53700000, \(dqsize_removed\(dq: 51100000, \(dqunknown_size_items\(dq: 0}}
+.EE
+.UNINDENT
+.UNINDENT
 .SS Sorting
 .sp
 Use \fB\-\-sort\-by FIELDS\fP where FIELDS is a comma\-separated list of fields.