compact: move --cleanup-commits description from examples to docs

docs/usage/compact.rst

@@ -7,9 +7,7 @@ Examples
     # compact segments and free repo disk space
     $ borg compact /path/to/repo
 
-    # same as above plus clean up 17byte commit-only segments,
-    # use this one time after upgrading borg (server) to 1.2+
-    # to clean up the tiny segments files created by borg 1.1:
+    # same as above plus clean up 17byte commit-only segments
     $ borg compact --cleanup-commits /path/to/repo
 
 

src/borg/archiver.py

@@ -2788,6 +2788,10 @@ class Archiver:
 
         When using ``--verbose``, borg will output an estimate of the freed space.
 
+        After upgrading borg (server) to 1.2+, you can use ``borg compact --cleanup-commits``
+        to clean up the numerous 17byte commit-only segments that borg 1.1 did not clean up
+        due to a bug. It is enough to do that once per repository.
+
         See :ref:`separate_compaction` in Additional Notes for more details.
         """)
         subparser = subparsers.add_parser('compact', parents=[common_parser], add_help=False,