diff --git a/docs/usage/compact.rst b/docs/usage/compact.rst
index f61375e08..2633d29eb 100644
--- a/docs/usage/compact.rst
+++ b/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
 
 
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
index 5848a7c73..03f91944c 100644
--- a/src/borg/archiver.py
+++ b/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,