From: Dirk Gouders <dirk@gouders.net>
To: Kyle Lippincott <spectral@google.com>
Cc: git@vger.kernel.org, Junio C Hamano <gitster@pobox.com>,
Emily Shaffer <emilyshaffer@google.com>
Subject: Re: [PATCH v2 4/5] MyFirstObjectWalk: fix description for counting omitted objects
Date: Sat, 23 Mar 2024 23:46:02 +0100 [thread overview]
Message-ID: <gh8r28zhw5.fsf@gouders.net> (raw)
In-Reply-To: <jikdly5drampltlvxuex67iz77isgt7uqcnf45ocmrozgbhyaq@2g7kucs2ordg> (Kyle Lippincott's message of "Sat, 23 Mar 2024 14:59:35 -0700")
Kyle Lippincott <spectral@google.com> writes:
> On Tue, Mar 19, 2024 at 12:23:14PM +0100, Dirk Gouders wrote:
>> 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.
>>
>> Signed-off-by: Dirk Gouders <dirk@gouders.net>
>> ---
>> Documentation/MyFirstObjectWalk.txt | 14 ++++++++------
>> 1 file changed, 8 insertions(+), 6 deletions(-)
>>
>> diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
>> index a06c712e46..981dbf917b 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`. We
>> +can ask `traverse_commit_list_filtered()` to populate the `omitted`
>> +list which 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.
>
> The way the original was phrased makes it sound to me like "Doing <stuff> via
> <mechanismA> is potentially slow.", and I expect a counter-proposal of using
> mechanismB to resolve that. The rewrite partially avoids that, but I think could
> take it further to really drive home that this is a consequence of using this
> new function, and is not a failing we will be proposing a solution for:
Yes, I had similar thoughts.
> We can ask `traverse_commit_list_filtered()` to populate the `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.
>
> Since that first sentence is now shorter, we could also add a bit more nuance to
> it, calling out that we're going to switch which function we're using earlier
> (and technically redundantly, but I think that's fine); something like the
> following:
>
> 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
> +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.
>
> Feel free to wordsmith any of my proposed text, and I apologize that these are
> just me typing in something that looks "patch like" in my mail client, not
> properly formatted patches. I think what you have is already an improvement,
> though, so if you think my proposed text is too verbose, I'm fine with what you
> have.
Thank you for your suggestion. To me, this fits much better and I will
use it should no further improvements being asked for.
>>
>> 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:
>> +You need to replace the call to `traverse_commit_list()` to
>
> If my proposal to introduce the point that we're switching which function we use
> in the earlier diff hunk is accepted, there's a small nit here: saying "You need
> to" would feel (very slightly) awkward, since we already mentioned that it was
> necessary to accomplish the goal. If we accept the previous proposal, we may
> want to change this to remove the "You need to", and just state something like
> "Replace the call..."
>
> Regardless, I think saying "replace the call to A _with_ B" (instead of "A _to_
> B") reads slightly better. I don't know if that's just a personal
> preference/dialect though.
When I wrote that "You need to" it felt semi-optimal even to me
non-native speaker, but I didn't exactly know what to do with it. So,
I'm very glad you are helping me to do all that better.
>> +`traverse_commit_list_filtered()` to be able to pass a pointer to the
>
> If we remove the "You need to", then we should probably rephrase this to more
> of an instruction, changing "to be able to" to "and".
>
> Something like this:
>
> -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:
Sounds way better and I'd use it.
Thanks again,
Dirk
next prev parent reply other threads:[~2024-03-23 22:46 UTC|newest]
Thread overview: 60+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-03-11 21:36 [PATCH 0/5] Fixes for Documentation/MyFirstObjectWalk.txt Dirk Gouders
2024-03-11 10:11 ` [PATCH 1/5] MyFirstObjectWalk: use additional arg in config_fn_t Dirk Gouders
2024-03-12 0:18 ` Junio C Hamano
2024-03-11 10:26 ` [PATCH 2/5] MyFirstObjectWalk: fix misspelled "builtins/" Dirk Gouders
2024-03-11 12:47 ` [PATCH 3/5] MyFirstObjectWalk: fix filtered object walk Dirk Gouders
2024-03-11 13:29 ` [PATCH 4/5] MyFirstObjectWalk: fix description for counting omitted objects Dirk Gouders
2024-03-11 21:00 ` [PATCH 5/5] MyFirstObjectWalk: add stderr to pipe processing Dirk Gouders
2024-03-12 0:13 ` Junio C Hamano
2024-03-12 14:27 ` Dirk Gouders
2024-03-12 19:29 ` Junio C Hamano
2024-03-12 0:15 ` [PATCH 0/5] Fixes for Documentation/MyFirstObjectWalk.txt Junio C Hamano
2024-03-19 11:23 ` [PATCH v2 " Dirk Gouders
2024-03-19 11:23 ` [PATCH v2 1/5] MyFirstObjectWalk: use additional arg in config_fn_t Dirk Gouders
2024-03-23 19:28 ` Kyle Lippincott
2024-03-19 11:23 ` [PATCH v2 2/5] MyFirstObjectWalk: fix misspelled "builtins/" Dirk Gouders
2024-03-19 11:23 ` [PATCH v2 3/5] MyFirstObjectWalk: fix filtered object walk Dirk Gouders
2024-03-19 11:23 ` [PATCH v2 4/5] MyFirstObjectWalk: fix description for counting omitted objects Dirk Gouders
2024-03-23 21:59 ` Kyle Lippincott
2024-03-23 22:46 ` Dirk Gouders [this message]
2024-03-19 11:23 ` [PATCH v2 5/5] MyFirstObjectWalk: add stderr to pipe processing Dirk Gouders
2024-03-23 19:48 ` Kyle Lippincott
2024-03-23 20:16 ` Dirk Gouders
2024-03-23 22:00 ` [PATCH v2 0/5] Fixes for Documentation/MyFirstObjectWalk.txt Kyle Lippincott
2024-03-23 23:06 ` Dirk Gouders
2024-03-24 2:20 ` Junio C Hamano
2024-03-25 12:33 ` [PATCH v3 " Dirk Gouders
2024-03-25 12:33 ` [PATCH v3 1/5] MyFirstObjectWalk: use additional arg in config_fn_t Dirk Gouders
2024-03-25 17:16 ` Junio C Hamano
2024-03-25 19:50 ` Dirk Gouders
2024-03-25 12:33 ` [PATCH v3 2/5] MyFirstObjectWalk: fix misspelled "builtins/" Dirk Gouders
2024-03-25 12:33 ` [PATCH v3 3/5] MyFirstObjectWalk: fix filtered object walk Dirk Gouders
2024-03-25 12:33 ` [PATCH v3 4/5] MyFirstObjectWalk: fix description for counting omitted objects Dirk Gouders
2024-03-25 17:25 ` Junio C Hamano
2024-03-25 20:07 ` Dirk Gouders
2024-03-25 21:25 ` Junio C Hamano
2024-03-25 20:59 ` Kyle Lippincott
2024-03-25 12:33 ` [PATCH v3 5/5] MyFirstObjectWalk: add stderr to pipe processing Dirk Gouders
2024-03-25 17:05 ` [PATCH v3 0/5] Fixes for Documentation/MyFirstObjectWalk.txt Kyle Lippincott
2024-03-25 20:07 ` Dirk Gouders
2024-03-25 17:50 ` Junio C Hamano
2024-03-25 18:01 ` Kyle Lippincott
2024-03-25 20:22 ` Dirk Gouders
2024-03-26 13:08 ` [PATCH v4 " Dirk Gouders
2024-03-27 1:04 ` Kyle Lippincott
2024-03-27 6:25 ` Dirk Gouders
2024-03-27 11:22 ` [PATCH v5 " Dirk Gouders
2024-03-27 11:22 ` [PATCH v5 1/5] MyFirstObjectWalk: use additional arg in config_fn_t Dirk Gouders
2024-03-27 11:22 ` [PATCH v5 2/5] MyFirstObjectWalk: fix misspelled "builtins/" Dirk Gouders
2024-03-27 11:22 ` [PATCH v5 3/5] MyFirstObjectWalk: fix filtered object walk Dirk Gouders
2024-03-27 11:22 ` [PATCH v5 4/5] MyFirstObjectWalk: fix description for counting omitted objects Dirk Gouders
2024-03-27 11:22 ` [PATCH v5 5/5] MyFirstObjectWalk: add stderr to pipe processing Dirk Gouders
2024-03-26 13:08 ` [PATCH v4 1/5] MyFirstObjectWalk: use additional arg in config_fn_t Dirk Gouders
2024-03-26 13:08 ` [PATCH v4 2/5] MyFirstObjectWalk: fix misspelled "builtins/" Dirk Gouders
2024-03-26 13:08 ` [PATCH v4 3/5] MyFirstObjectWalk: fix filtered object walk Dirk Gouders
2024-03-26 13:08 ` [PATCH v4 4/5] MyFirstObjectWalk: fix description for counting omitted objects Dirk Gouders
2024-03-26 17:00 ` Junio C Hamano
2024-03-26 20:09 ` Dirk Gouders
2024-03-26 20:24 ` Junio C Hamano
2024-03-27 6:30 ` Dirk Gouders
2024-03-26 13:08 ` [PATCH v4 5/5] MyFirstObjectWalk: add stderr to pipe processing Dirk Gouders
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=gh8r28zhw5.fsf@gouders.net \
--to=dirk@gouders.net \
--cc=emilyshaffer@google.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=spectral@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).