On Mon, Mar 25, 2024 at 10:25 AM Junio C Hamano <gitster@xxxxxxxxx> wrote:
>
> Dirk Gouders <dirk@xxxxxxxxxxx> 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 <spectral@xxxxxxxxxx>
> > Signed-off-by: Dirk Gouders <dirk@xxxxxxxxxxx>
> > ---
> > 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 ...
This proposed text has a small ambiguity, it can be parsed as:
- Note that (with this function) our object walk will not perform any
better than an unfiltered walk [implying that the function change
itself is the cause of the performance concern]
or
- Note that (our object walk) will not perform any better than an
(unfiltered walk with this function) [implying that
`traverse_commit_list_filtered` has a filtered and an unfiltered mode
of operation [which it does...]]
The issue is that the name `traverse_commit_list_filtered` is poorly
named: `traverse_commit_list` and `traverse_commit_list_filtered` are
the exact same function (both support filtering!), it's just that
`traverse_commit_list_filtered` is able to announce what was filtered.
Perhaps:
Note that requesting the list of filtered objects may have
performance implications; all reachable objects will be visited in
order to populate the list of filtered objects.
I'm intentionally being ambiguous about it _definitely_ having
performance implications, because it's context dependent. It looks
like only the `filter_trees_depth` function actually changes what it
visits depending on whether the omits list was specified or not.
>
> > +will not perform any better than an unfiltered object walk; all reachable
> > +objects are walked in order to populate the list.
>
> Other than that, looking very good.
>
> Thanks, both.
>
> > First, add the `struct oidset` and related items we will use to iterate it:
> >
> > @@ -778,8 +779,9 @@ static void walken_object_walk(
> > ...
> > ----
> >
> > -Modify the call to `traverse_commit_list_filtered()` to include your `omitted`
> > -object:
> > +Replace the call to `traverse_commit_list()` with
> > +`traverse_commit_list_filtered()` and pass a pointer to the `omitted` oidset
> > +defined and initialized above:
> >
> > ----
> > ...
