Repository: borgbackup/borg

Issue:
1.1.0b6: Meaning of "max. archive size" unclear
`borg info` has a new entry:
```
Utilization of max. archive size: 0%
```

So what does this mean?
I assume this is https://github.com/borgbackup/borg/pull/2565, so it is a storage quota, but does not it apply to the whole repo, not only to one archive?
So does not it have to say this?
```
Utilization of max. repo size: 0%
```

Or do you mean?
```
How much size this archive utilises in the whole repo: 0%
```

~~Then I would suggest something like this (it's in a more readable shorter way):~~
~~Part of max. repo size: 0%~~

Well… no, it basically means the same as "Utilization of max. repo size". I think that wording is okay.


Discussion:
Just noticed in case of no storage quota (as it's the default), "How much size this archive utilises in the whole repo" cannot be 0%, as it would also apply without storage quotas, but this does not seem to be the case, so actually I think it only applies to storage quotas.
it is referring to the max. size of the metadata stream.
(the maximum archive size borg can process)
Ohh, okay. :open_mouth:  Is this documented anywhere?

If it is such a strange thing, which may be only useful for debugging, why show it at all there?
As said, my tries to explain the thing, were wrong, but they could still make sense it would be quite useful to check that you do not exceed your quota e.g., but why on hell should a normal borg user (so no dev/no debugging) need this information?
I mean this limit is likely/hopefully a very big number (some terrabyte or so)… @enkore [once said](https://github.com/borgbackup/borg/issues/37#issuecomment-309247108) borg works with >40TB… so the limit must certainly be higher than 40 TB…
And if it is so high, 90% of the borg user may not even get 5% in the information screen and as such the information is largely useless for an average user, who does not create incredible huge archives.

BTW what is the max archive size "borg can process"? Is that be a hard limit?
You can hit that limit within a few dozen GB; it's essentially unrelated to the size of the files.

The meaning of this should be documented in the borg info help page, yes.
> You can hit that limit within a few dozen GB; it's essentially unrelated to the size of the files.

That's interesting. But it is archive-specific?

And do you still think this is an information, which should be visible to the end-user? I mean likely you could also show a user the number of chunks used in an archive, but usually the user does not care/it does not matter, …

Resolving patch:
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -1415,7 +1415,7 @@ def format_cmdline(cmdline):
                 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}
@@ -3211,9 +3211,14 @@ def define_archive_filters_group(subparser, *, sort_by=True, first_last=True):
         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__,
@@ -3525,8 +3530,9 @@ def define_archive_filters_group(subparser, *, sort_by=True, first_last=True):
         .. 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__,


Test patch: