Merge pull request #2873 from enkore/issue/2869

with-lock, info docs

src/borg/archiver.py

@@ -1416,7 +1416,7 @@ class Archiver:
                 Duration: {duration}
                 Number of files: {stats[nfiles]}
                 Command line: {command_line}
-                Utilization of max. archive size: {limits[max_archive_size]:.0%}
+                Utilization of maximum supported archive size: {limits[max_archive_size]:.0%}
                 ------------------------------------------------------------------------------
                                        Original size      Compressed size    Deduplicated size
                 This archive:   {stats[original_size]:>20s} {stats[compressed_size]:>20s} {stats[deduplicated_size]:>20s}
@@ -3212,9 +3212,14 @@ class Archiver:
         are meaning different things:
 
         This archive / deduplicated size = amount of data stored ONLY for this archive
-                                         = unique chunks of this archive.
+        = unique chunks of this archive.
         All archives / deduplicated size = amount of data stored in the repo
-                                         = all chunks in the repository.
+        = all chunks in the repository.
+
+        Borg archives can only contain a limited amount of file metadata.
+        The size of an archive relative to this limit depends on a number of factors,
+        mainly the number of files, the lengths of paths and other metadata stored for files.
+        This is shown as *utilization of maximum supported archive size*.
         """)
         subparser = subparsers.add_parser('info', parents=[common_parser], add_help=False,
                                           description=self.do_info.__doc__,
@@ -3526,8 +3531,9 @@ class Archiver:
         .. note::
 
             If you copy a repository with the lock held, the lock will be present in
-            the copy, obviously. Thus, before using borg on the copy, you need to
-            use "borg break-lock" on it.
+            the copy. Thus, before using borg on the copy from a different host,
+            you need to use "borg break-lock" on the copied repository, because
+            Borg is cautious and does not automatically remove stale locks made by a different host.
         """)
         subparser = subparsers.add_parser('with-lock', parents=[common_parser], add_help=False,
                                           description=self.do_with_lock.__doc__,