Subject: Re: [PATCH v3 4/5] MyFirstObjectWalk: fix description for counting omitted objects

From: Dirk Gouders <[email-masked]>
Date: Mon, 25 Mar 2024 21:07:03 +0100

Junio C Hamano <[email-masked]> writes:

> Dirk Gouders <[email-masked]> writes:
>
>> Before the changes to count omitted objects, the function
>> traverse_commit_list() was used and its call cannot be changed to pass
>> a pointer to an oidset to record omitted objects.
>>
>> Fix the text to clarify that we now use another traversal function to
>> be able to pass the pointer to the introduced oidset.
>>
>> Helped-by: Kyle Lippincott <[email-masked]>
>> Signed-off-by: Dirk Gouders <[email-masked]>
>> ---
>>  Documentation/MyFirstObjectWalk.txt | 14 ++++++++------
>>  1 file changed, 8 insertions(+), 6 deletions(-)
>>
>> diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
>> index a06c712e46..811175837c 100644
>> --- a/Documentation/MyFirstObjectWalk.txt
>> +++ b/Documentation/MyFirstObjectWalk.txt
>> @@ -754,10 +754,11 @@ points to the same tree object as its grandparent.)
>>  === Counting Omitted Objects
>>  
>>  We also have the capability to enumerate all objects which were omitted by a
>> -filter, like with `git log --filter=<spec> --filter-print-omitted`. Asking
>> -`traverse_commit_list_filtered()` to populate the `omitted` list means that our
>> -object walk does not perform any better than an unfiltered object walk; all
>> -reachable objects are walked in order to populate the list.
>> +filter, like with `git log --filter=<spec> --filter-print-omitted`. To do this,
>> +change `traverse_commit_list()` to `traverse_commit_list_filtered()`, which is
>> +able to populate an `omitted` list. Note that this means that our object walk
>
> "this means that" could be rephrased in a way a bit more helpful and
> to readers with clarity, perhaps:
>
> 	Note that our object walk will not perform any better than
> 	an unfiltered walk with this function, because all reachable
> 	objects need to be walked in order to ...

Would it be OK to rearrange it even more?  To me, the above raises the
new question "How do I use traverse_commit_list_filtered() to do an
unfiltered walk?":

 	Note that our object walk with this function will not perform
	any better than the previous unfiltered walk, because all
	reachable objects need to be walked in order to ...

Dirk