Step 5's borg list sample predated the timezone offset in the default
timestamp format (regenerated from a real run); the delete step claimed
a NAME "might match multiple archives" - borg aborts unless the name
matches exactly one archive; point at aid: and -a instead.
Co-Authored-By: Claude Fable 5 <[email protected]>
- quickstart: no segments in borg2 (packs/unreferenced-objects
wording); backend list is file:/rest: plus sftp/s3/b2; fix the
example script's exit-code handling for BORG_EXIT_CODES=modern
(highest-rc-wins ranked warnings 100..127 above errors 3..99 and
the rc==1 warning branch was dead) with a severity classifier;
regenerate the --stats and repo-list samples from real runs; make
the prose repo path match the script's rest:// URL; typos; correct
the repository model description (no manifest tracking blocks).
- repository-urls: use rest:// in the BORG_REPO example (ssh:// is
legacy-only, as the same file says).
- file-systems: rewrite for packs (chunks are grouped into pack files
of up to ~50 MB; compact works at pack granularity).
- resources: borg repo-delete (not "delete repo", not server-side);
replace the false "single-threaded, max 100% of one core" claim
with the real multi-threaded cases (zstd, blake3, pack writer).
- positional-arguments: drop borg1 repo::archive wording.
- config: fix the --print_config example (must precede the
subcommand) and the related prose.
- usage_general.rst.inc (man intro): add the archive-specification
and config includes that were only added to the usage variant when
the two files diverged (oversight from the #4587 split; the
archive-specification include uses :start-after: to avoid a
duplicate label).
- fix dead links: IEC binary prefixes (wikipedia anchor moved),
paperkey.html in the borg 1.x changelog.
- misc: update benchmark-crud commands to borg2 (with a note that the
numbers are borg1-era); add a preamble to create_chunker-params
noting it predates borg2/fastcdc.
Co-Authored-By: Claude Fable 5 <[email protected]>
"--encryption=none" and "--encryption=authenticated" have not existed since
the id hash became part of the mode name for the modes that do not encrypt:
they are now "none-sha256"/"none-blake3" and "authenticated-sha256"/
"authenticated-blake3". The examples in docs/usage/repo-create.rst still used
the old names, so copying them gave an argparse error.
The "authenticated --id-hash=blake3" example was doubly wrong: those modes
name their id hash themselves and reject a separate --id-hash. Replaced it
with plain "authenticated-blake3"/"none-blake3" examples and dropped the
now-wrong claim that the non-encrypting modes only support sha256.
Also:
- "--encryption=aes-ocb" (docs/usage/key.rst, docs/quickstart_example.rst.inc)
is not a valid mode either, it is "aes256-ocb".
- scripts/rest_perf_test.sh used "--encryption none".
- regenerated the affected man pages; borg-repo-create(1) additionally picked
up the already-fixed --key-location help text.
All examples were verified by actually running them.
Borg used to read the manifest's key-type byte and then look for the key in
exactly one place (keyfile or repokey) depending on the key class that byte
selected. As a result every crypto suite was duplicated into a keyfile class
and a repokey class that differed only in TYPE, NAME, ARG_NAME and STORAGE.
Now key *location* is independent of the type byte: detection tries keyfiles
first and repokeys afterwards until a passphrase unlocks a key. The type byte
still selects the crypto suite (id hash, MAC, cipher) to instantiate. Where a
key is stored (keyfile vs repokey) is therefore a per-key property
(self.storage), not a separate class, so a repository may even hold a mix of
keyfile- and repo-stored borg keys.
With storage decoupled from class identity, the keyfile/repokey class pairs
collapse into one class per crypto suite:
- modern AEAD: AESOCBKey, CHPOKey, Blake3AESOCBKey, Blake3CHPOKey
- legacy borg 1.x (read-only): AESCTRKey, Blake2AESCTRKey
There is now exactly one type byte per modern crypto suite (the old separate
repokey type bytes 0x11/0x21/0x31/0x41 were removed; borg2 is beta and only
needs to read repos it created). identify_key() matches on TYPES_ACCEPTABLE.
CLI: --encryption selects only the crypto suite (aes-ocb, chacha20-poly1305,
blake3-aes-ocb, blake3-chacha20-poly1305, authenticated*, none); the storage
location is chosen with the new --key-location=repokey|keyfile (default
repokey). The old combined modes (repokey-aes-ocb etc.) were removed.
borg key import also gained --key-location. borg key change-location no longer
swaps key classes or rewrites the manifest; it just re-saves the unlocked key
at the new location.
Keyfile removal (key remove, change-location) now overwrites the keyfile with
random data via secure_erase() before unlinking, consistent with save().
borg 1.x legacy read compatibility is preserved (the legacy class merge is a
behavior-preserving rename; the legacy type bytes incl. PASSPHRASE stay in
TYPES_ACCEPTABLE).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
in borg 1.x, we used to put a timestamp into the archive name to make
it unique, because borg1 required that.
borg2 does not require unique archive names, but it encourages you
to even use an identical archive name within the same SERIES of archives.
that makes matching (e.g. for prune, but also at other places) much
simpler and borg KNOWS which archives belong to the same series.
at some places, the docs were not updated yet.
for borg 1.x, -a (aka --glob-archives) expected
sh: style glob patterns ONLY (but one must not
give sh: explicitly).
for borg 2, -a (aka --match-archives) defaults
to id: style (identical match), so one must give
sh: if one wants shell-style globbing.
One cannot "to not x", but one can "not to x".
Avoiding split infinitives gives the added bonus that machine
translation yields better results.
setup (n/adj) vs set(v) up. We don't "I setup it" but "I set it up".
Likewise for login(n/adj) and log(v) in, backup(n/adj) and back(v) up.
