rev-list-options: fix off-by-one in '--filter=blob:limit=<n>' explainer

[edigaryev]

'--filter=blob:limit=' was introduced in 25ec7bc (list-objects: filter objects in traverse_commit_list, 2017-11-21) and later expanded to bitmaps in 84243da (pack-bitmap: implement BLOB_LIMIT filtering, 2020-02-14)

The logic that was introduced in these commits (and that still persists to this day) omits blobs larger than or equal to n bytes or units.

However, the documentation (Documentation/rev-list-options.txt) states:

The form '--filter=blob:limit=[kmg]' omits blobs larger than n
bytes or units. n may be zero.

Moreover, the t6113-rev-list-bitmap-filters.sh tests for exactly this logic, so it seems it is the documentation that needs fixing, not the code.

This changes the explanation to be similar to
Documentation/git-clone.txt, which is correct.

[edigaryev]

/submit

[gitgitgadget-git]

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-git-1645/edigaryev/fix-blob-limit-off-by-one-v1

To fetch this version to local tag pr-git-1645/edigaryev/fix-blob-limit-off-by-one-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-git-1645/edigaryev/fix-blob-limit-off-by-one-v1

[gitgitgadget-git]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Nikolay Edigaryev via GitGitGadget" <[email protected]>
writes:

> From: Nikolay Edigaryev <[email protected]>
>
> '--filter=blob:limit=<n>' was introduced in 25ec7bcac0 (list-objects:
> filter objects in traverse_commit_list, 2017-11-21) and later expanded
> to bitmaps in 84243da129 (pack-bitmap: implement BLOB_LIMIT filtering,
> 2020-02-14)
>
> The logic that was introduced in these commits (and that still persists
> to this day) omits blobs larger than _or equal_ to n bytes or units.

Good eyes.  The former does this

		if (object_length < filter_data->max_bytes)
			goto include_it;

and the latter does this


                if (!bitmap_get(tips, pos) &&
                    get_size_by_pos(bitmap_git, pos) >= limit)
                        bitmap_unset(to_filter, pos);

> However, the documentation (Documentation/rev-list-options.txt) states:
>
>>The form '--filter=blob:limit=<n>[kmg]' omits blobs larger than n
> bytes or units. n may be zero.
>
> Moreover, the t6113-rev-list-bitmap-filters.sh tests for exactly this
> logic, so it seems it is the documentation that needs fixing, not the
> code.

Yup.  The mechanism is used for things like "we do not want a large
blob, like 100MB", and a byte on the boundary does not matter all
that much in such a countext, but it does not hurt to be more
correct ;-)

>  The form '--filter=blob:none' omits all blobs.
>  +
> -The form '--filter=blob:limit=<n>[kmg]' omits blobs larger than n bytes
> -or units.  n may be zero.  The suffixes k, m, and g can be used to name
> -units in KiB, MiB, or GiB.  For example, 'blob:limit=1k' is the same
> -as 'blob:limit=1024'.
> +The form '--filter=blob:limit=<n>[kmg]' omits blobs of size at least n
> +bytes or units.  n may be zero.  The suffixes k, m, and g can be used
> +to name units in KiB, MiB, or GiB.  For example, 'blob:limit=1k'
> +is the same as 'blob:limit=1024'.

With unnecessary paragraph wrapping, it is a bit hard to compare the
preimage and the postimage, but I manually checked that this only
does

	"larger than" -> "of size at least"

and nothing else, which is expected and in line with what the
proposed commit message claimed to do.  Good job.

Will queue.  Thanks.

>  +
>  The form '--filter=object:type=(tag|commit|tree|blob)' omits all objects
>  which are not of the requested type.
>
> base-commit: 564d0252ca632e0264ed670534a51d18a689ef5d

[gitgitgadget-git]

This branch is now known as ne/doc-filter-blob-limit-fix.

[gitgitgadget-git]

This patch series was integrated into seen via a45d645.

[gitgitgadget-git]

There was a status update in the "New Topics" section about the branch ne/doc-filter-blob-limit-fix on the Git mailing list:

Docfix.

Will merge to 'next'.
source: <[email protected]>

[gitgitgadget-git]

This patch series was integrated into seen via bae6296.

[gitgitgadget-git]

This patch series was integrated into seen via 3d6510d.

[gitgitgadget-git]

This patch series was integrated into seen via 101ef5c.

[gitgitgadget-git]

This patch series was integrated into next via 4f78975.

[gitgitgadget-git]

There was a status update in the "Cooking" section about the branch ne/doc-filter-blob-limit-fix on the Git mailing list:

Docfix.

Will merge to 'master'.
source: <[email protected]>

[gitgitgadget-git]

This patch series was integrated into seen via 1d262b7.

[gitgitgadget-git]

This patch series was integrated into seen via 531e73d.

[gitgitgadget-git]

This patch series was integrated into seen via 9d9a662.

[gitgitgadget-git]

There was a status update in the "Cooking" section about the branch ne/doc-filter-blob-limit-fix on the Git mailing list:

Docfix.

Will merge to 'master'.
source: <[email protected]>

[gitgitgadget-git]

This patch series was integrated into seen via cf63945.

[gitgitgadget-git]

This patch series was integrated into seen via 9c6a09d.

[gitgitgadget-git]

This patch series was integrated into seen via f3657b3.

[gitgitgadget-git]

This patch series was integrated into master via f3657b3.

[gitgitgadget-git]

This patch series was integrated into next via f3657b3.

[gitgitgadget-git]

Closed via f3657b3.