upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-04-21 22:29:54 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: add prominent note to borg create about archive series and files cache; recommend stable NAME per series for performance (#8955)

Browse source
This commit is contained in:
Thomas Waldmann 2025-11-10 02:37:55 +01:00
parent d423dd4acd
commit 71ca0ac6a7
No known key found for this signature in database
GPG key ID: 243ACFA951F78E01
1 changed files with 13 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
docs/usage/create.rst
View file

@ -1,5 +1,18 @@
.. include:: create.rst.inc
.. note::
Archive series and performance: In Borg 2, archives that share the same NAME form an "archive series".
The files cache is maintained per series. For best performance on repeated backups, reuse the same
NAME every time you run ``borg create`` for the same dataset (e.g. always use ``my-documents``).
Frequently changing the NAME (for example by embedding date/time like ``my-documents-2025-11-10``)
prevents cache reuse and forces Borg to re-scan and re-chunk files, which can make incremental
backups vastly slower. Only vary the NAME if you intentionally want to start a new series.
If you must vary the archive name but still want cache reuse across names, see the advanced
knobs described in :ref:`upgradenotes2` (``BORG_FILES_CACHE_SUFFIX`` and ``BORG_FILES_CACHE_TTL``),
but the recommended approach is to keep a stable NAME per series.
Examples
~~~~~~~~
::