From: Taylor Blau <me@ttaylorr.com>
Date: Thu, 29 Jan 2026 19:34:27 GMT
Subject: Re: [PATCH 2/3] pack-bitmap: fix bug with exact ref match in "pack.preferBitmapTips"
Message-ID: <aXu2Q1TgsaUIo30+@nand.local>
In-Reply-To: <xmqq7bt0cqec.fsf@gitster.g>

On Thu, Jan 29, 2026 at 08:52:43AM -0800, Junio C Hamano wrote:
> Taylor Blau <me@ttaylorr.com> writes:
>
> > 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 ---

> > 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