midx docs: clarify tie breaking

Clarify what happens when an object exists in more than one pack, but
not in the preferred pack. "git multi-pack-index repack" relies on ties
for objects that are not in the preferred pack being resolved in favor
of the newest pack that contains a copy of the object. If ties were
resolved in favor of the oldest pack as the current documentation
suggests the multi-pack index would not reference any of the objects in
the pack created by "git multi-pack-index repack".

Helped-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-multi-pack-index.adoc b/Documentation/git-multi-pack-index.adoc
index 631d5c7d15c0de14529793061e80769560ec80b3..b6cd0d7f855d5fe645801f562371afcd547e0dd8 100644 (file)
--- a/Documentation/git-multi-pack-index.adoc
+++ b/Documentation/git-multi-pack-index.adoc
@@ -38,10 +38,13 @@ write::
 +
 --
        --preferred-pack=<pack>::
-               Optionally specify the tie-breaking pack used when
-               multiple packs contain the same object. `<pack>` must
-               contain at least one object. If not given, ties are
-               broken in favor of the pack with the lowest mtime.
+               When specified, break ties in favor of this pack when
+               there are additional copies of its objects in other
+               packs. Ties for objects not found in the preferred
+               pack are always resolved in favor of the copy in the
+               pack with the highest mtime. If unspecified, the pack
+               with the lowest mtime is used by default. The
+               preferred pack must have at least one object.
 
        --[no-]bitmap::
                Control whether or not a multi-pack bitmap is written.