On Thu, Jan 29, 2026 at 08:52:43AM -0800, Junio C Hamano wrote:

Taylor Blau [off-list ref] writes:

quoted

Looking at the implementation of bitmap_writer_select_commits(), we do
not guarantee that *any* reference specified by pack.preferBitmapTips
will receive a bitmap. That's because we don't necessarily enumerate the
entire set of commits when determining which ones to bitmap.

Hmph.  Is this documented?

	... Goes and looks ...

Yes, it is documented.  We say "This is because ..." but it just
explains it as what the chosen design of the implementation happens
to do, without saying for what benefit the implementation was chosen,
so it is unclear if this is designed behaviour, or more importantly,
even if this were designed, what the rationale of choosing that
design was.

"When they are so close to fall into the same chunk, there is no
point having bitmaps individually for them, as their bitmaps will be
very similar anyway, so this design saves space without sacrificing
the quality of the resulting set of bitmaps" or something?

The commits are generally presented in the order they are traversed
(regardless of whether we are generating single- or multi-pack bitmaps).
That makes it likely that commits within the same window are likely to
generate very similar bitmaps, but it is not guaranteed.

When looking at the documentation, I ended up with the following:

--- 8< ---
diff --git a/Documentation/config/pack.adoc b/Documentation/config/pack.adoc
index 75402d5579d..b65cbaaebb4 100644
--- a/Documentation/config/pack.adoc
+++ b/Documentation/config/pack.adoc

@@ -168,7 +168,10 @@ pack.preferBitmapTips::
 Note that setting this configuration to `refs/foo` does not mean that
 the commits at the tips of `refs/foo/bar` and `refs/foo/baz` will
 necessarily be selected. This is because commits are selected for
-bitmaps from within a series of windows of variable length.
+bitmaps from within a series of windows of variable length (in order to
+space bitmaps out throughout history), and we only select one commit per
+window. Thus if multiple preferred commits appear in the same window,
+only one will be selected.
 +
 If a commit at the tip of any reference which is a suffix of any value
 of this configuration is seen in a window, it is immediately given
--- >8 ---

quoted

At the very least, if we do end up going in this direction (and I am not
necessarily advocating that we do, since I would prefer a more
consistent set of behavior), we should at minimum document it in
git-config(1).

The documentation says "... reference that is a suffix of any value
of this configuration".  Is "refs/heads/foobar" a "suffix" of
"refs/heads/foo"?  I actually find this phrasing fairly strange, as
I do not think of "refs/heads/main" be a "suffix" of "refs/heads/".

I agree, the use of "suffix" is confusing at best. I think if/how we
change this section depends on the outcome of this series, but the
original intent was to say that preferring "refs/heads/foo" would make
the commits at the tips of "refs/heads/foo/bar" and "refs/heads/foo/baz"
preferred, but not "refs/heads/foobar".

Thanks,
Taylor