Re: [PATCH v4 0/5] Fixes for Documentation/MyFirstObjectWalk.txt

> The 4th round of this series.
> 
> Chances are that I just waste your time with my attemt [4/5].
> My appologies in advance, should this be the case.
> 
> Recently, there was a discussion [1] on the groff mailing list and I
> guess I couldn't resist to try to practice what I read in the linked
> resources ;-)
> 
> [1] https://lists.gnu.org/archive/html/groff/2024-03/msg00014.html
> 
> Could be that the remaining controversal part of [4/5] should just be
> left untouched, because it is consuming so much time -- I summarized
> all those versions, so that all incarnations can be compared in one
> view:
> 
> * Original:
> 
> 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.
> 
> * v3:
> 
> Note that this means that our object walk will not perform any better
> than an unfiltered object walk; all reachable objects are walked in
> order to populate the list.
> 
> * Junio's suggestion (with minor rearrangement):
> 
> 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 populate the list of filtered
> objects.
> 
> * Kyle's suggestion:
> 
> 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.
> 
> * My new attempt (v4):
> 
> This list of filtered objects may have performance implications,
> however, because despite filtering objects, the possibly much larger
> set of all reachable objects must be processed in order to populate
> that list.

> 
> --
> Changes in v4:
> * Used the proper `git show` for references in [1/5] and [3/5]
> * Another attempt to write clear speach in [4/5]
> 
> Changes in v3:
> * Reword the description in [4/5]
> * Add a missing slash in [5/5]
> 
> Changes in v2:
> * Added Emily to Cc in the hope for a review
> * Remove superfluous tags from [1/5] and [3/5]
> * Replace bashism `|&` by `2>&1 |` in [5/5]
> --
> Dirk Gouders (5):
>   MyFirstObjectWalk: use additional arg in config_fn_t
>   MyFirstObjectWalk: fix misspelled "builtins/"
>   MyFirstObjectWalk: fix filtered object walk
>   MyFirstObjectWalk: fix description for counting omitted objects
>   MyFirstObjectWalk: add stderr to pipe processing
> 
>  Documentation/MyFirstObjectWalk.txt | 37 ++++++++++++++++-------------
>  1 file changed, 21 insertions(+), 16 deletions(-)
> 
> Range-diff against v3:
> 1:  0eeb4b78ac ! 1:  102cbc54c4 MyFirstObjectWalk: use additional arg in config_fn_t
>     @@ Metadata
>       ## Commit message ##
>          MyFirstObjectWalk: use additional arg in config_fn_t
>      
>     -    Commit a4e7e317 (config: add ctx arg to config_fn_t) added a fourth
>     -    argument to config_fn_t but did not change relevant function calls
>     -    in Documentation/MyFirstObjectWalk.txt.
>     +    Commit a4e7e317f8 (config: add ctx arg to config_fn_t, 2023-06-28)
>     +    added a fourth argument to config_fn_t but did not change relevant
>     +    function calls in Documentation/MyFirstObjectWalk.txt.
>      
>          Fix those calls and the example git_walken_config() to use
>          that additional argument.
> 2:  3122ae2472 = 2:  5fb7953f31 MyFirstObjectWalk: fix misspelled "builtins/"
> 3:  f21348ab80 ! 3:  b88518df0b MyFirstObjectWalk: fix filtered object walk
>     @@ Metadata
>       ## Commit message ##
>          MyFirstObjectWalk: fix filtered object walk
>      
>     -    Commit f0d2f849 (MyFirstObjectWalk: update recommended usage)
>     -    changed a call of parse_list_objects_filter() in a way that
>     -    probably never worked: parse_list_objects_filter() always needed a
>     -    pointer as its first argument.
>     +    Commit f0d2f84919 (MyFirstObjectWalk: update recommended usage,
>     +    2022-03-09) changed a call of parse_list_objects_filter() in a way
>     +    that probably never worked: parse_list_objects_filter() always needed
>     +    a pointer as its first argument.
>      
>          Fix this by removing the CALLOC_ARRAY and passing the address of
>          rev->filter to parse_list_objects_filter() in accordance to
> 4:  cfa4b9ce50 ! 4:  11510630af MyFirstObjectWalk: fix description for counting omitted objects
>     @@ Documentation/MyFirstObjectWalk.txt: points to the same tree object as its grand
>      -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
>     -+will not perform any better than an unfiltered object walk; all reachable
>     -+objects are walked in order to populate the list.
>     ++able to populate an `omitted` list.  This list of filtered objects may have
>     ++performance implications, however, because despite filtering objects, the possibly
>     ++much larger set of all reachable objects must be processed in order to
>     ++populate that list.
>       
>       First, add the `struct oidset` and related items we will use to iterate it:
>       
> 5:  c571abb49d = 5:  8920313ee2 MyFirstObjectWalk: add stderr to pipe processing
> -- 
> 2.43.0
>