Re: [PATCH v6 0/5] doc: git-rebase: clarify DESCRIPTION section

[Junio C Hamano <gitster@pobox.com>]

"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".

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":

or something.