From: Phillip Wood <phillip.wood123@gmail.com>
Date: Fri, 15 Aug 2025 10:25:13 GMT
Subject: Re: [PATCH v6 0/5] doc: git-rebase: clarify DESCRIPTION section
Message-ID: <c9a4d7ef-8cdf-4d5b-b0af-f43ffc6b7450@gmail.com>
In-Reply-To: <xmqq5xepzjnu.fsf@gitster.g>

On 14/08/2025 22:18, Junio C Hamano wrote:
> "Julia Evans" <julia@jvns.ca> writes:
> 
>>> well given they're also both pretty niche. I'd also be very happy to go
>>> with Junio's suggestion to replace steps 1 & 2 with a general
>>> description that does not mention 'git log' at all.
>>
>> I like the idea of leaving out `--fork-point` and `--root`.
>>
>> Now that I know the use case for `--reapply-cherry-picks`: what I like about
>> leaving in the `git log` description is that I think it makes it easier for
>> folks to build a mental model of why a `git rebase` might be slow: there's a
>> "fast step" (the `git log` step) and a "slow step" (the `git patch-id` step).
 >
> But that is not what goes on, is it?  What you wrote as if they were
> two separate steps (1 to enumerate, 2 to filter) is not what happens
> in practice.  Whether it is done via the "format-patch --stdout | am"
> pipeline in run_am(), or via the "rev-list --reverse | xargs -n1
> cherry-pick" pipeline in run_sequencer_rebase(), the upstream of
> these conceptual pipelines that enumerates what is to be replayed is
> run just once, i.e. there is only one step that "enumerates what is
> to be replayed", without a separate filtering step.
> 
> In other words, there is no "a fast step followed by a slow step".

Although the cherry-pick detection happens inside "git log" that command 
has a fast step (find the commits on both sides of the merge base) and a 
slow step (detect cherry-picks) so I think it depends where one draws 
the step boundaries. The cherry-pick detection is known to be slow when 
there are a lot of new upstream commits which was the motivation for 
adding --reapply-cherry-picks in 0fcb4f6b62 (rebase --merge: optionally 
skip upstreamed commits, 2020-04-11)

> Perhaps squashing the first two steps into one and phrasing them as
> a single step is sufficient to give a conceptual overview (what you
> have in v7 as "a simplified description of what the command does").
> 
>   1. Make a list of all commits on your current branch since it
>      branched off from `<upstream>` that do not have equivalent
>      change in `<upstream>`.
> 
> If you want to keep 1 & 2 separate, then rephrase the introductory
> sentence to clarify that we are giving a white lie for the sake of
> easier understanding, e.g.
> 
>      Here is what conceptually happens in "git rebase":

Either of those sounds reasonable to me

Thanks

Phillip