Merge pull request #9114 from ThomasWaldmann/doc/compact-threshold-max-9112

doc: compact threshold — document how to get maximum compaction (#9112)

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