Re: [PATCH 2/3] pack-bitmap: fix bug with exact ref match in "pack.preferBitmapTips"

[Junio C Hamano <gitster@pobox.com>]

Taylor Blau <me@ttaylorr.com> writes:

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

That's certainly better.

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

I am still not sure if naming an individual ref is an intended use,
but I assume that the original intent of this part of the document
was to specify the leading hierarchies and commits at the tip of
refs that appear in one of the listed hiearchies are used as
preferred candidates to give bitmaps.

    pack.preferBitmapTips::

	Specifies a ref hierarchy (e.g., "refs/heads/"); can be
	given multiple times to specify more than one hierarchies.

	When selecting which commits will receive bitmaps, prefer a
        commmit at the tip of a reference that appears in one of the
        hierarchies specified over any other commits ...


or something?