From 177f7d5b9abbfd94c3c1fd4f0369890ea85e9078 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Thu, 30 Oct 2025 11:08:17 +0100 Subject: [PATCH] docs(compact): explain how to get maximum compaction with --threshold 0 and trade-offs (#9112, discussion #8716) --- src/borg/archiver.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 0e660d5f4..4a4850c16 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -3542,6 +3542,13 @@ class Archiver: 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 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