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

[Phillip Wood <phillip.wood123@gmail.com>]

Hi Julia

On 11/08/2025 22:51, Julia Evans via GitGitGadget wrote:
>   * move "You can also use git rebase to reorder or combine commits:" to the
>     beginning

Great

>   * replace "detailed description" with "simplified description" -- I thought
>     that I could write something that was relatively readable and also
>     accurate, but as usual Git has proven me wrong :). I tried to leave in
>     the details that I think seem relevant to using git: for example git
>     checkout --detach is relevant because it explains why git reflog works
>     well after a rebase.
>   * replace the git switch with git checkout that I'd missed previously
> 
> I didn't use the git log --cherry-pick option in the explanation because I
> had personally never heard of that option before today, and I don't want
> people to have to read the git log man page to be able to understand the
> explanation. I also left out --reapply-cherry-picks just because I don't
> understand the use case so I couldn't evaluate how likely it is to be
> relevant to the person reading.
The use case for --reapply-cherry-picks is mostly that it is faster to 
try picking a commit and then drop it if it results in a empty change 
than it is to do the patch-id comparisons to avoid picking the commit in 
the first place. This is especially true on partial clones where the 
cherry-pick detection is really slow. I'm happy to leave it out but I 
wonder if we should drop the references to --fork-point and --root as 
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.

Thanks

Phillip

> 
> Julia Evans (5):
>    doc: git-rebase: start with an example
>    doc: git rebase: dedup merge conflict discussion
>    doc: git rebase: clarify arguments syntax
>    doc: git-rebase: move --onto explanation down
>    doc: git-rebase: update discussion of internals
> 
>   Documentation/git-rebase.adoc | 302 +++++++++++++++-------------------
>   1 file changed, 136 insertions(+), 166 deletions(-)
> 
> 
> base-commit: 2c2ba49d55ff26c1082b8137b1ec5eeccb4337d1
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1949%2Fjvns%2Fclarify-rebase-v6
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1949/jvns/clarify-rebase-v6
> Pull-Request: https://github.com/gitgitgadget/git/pull/1949
> 
> Range-diff vs v5:
> 
>   1:  c2f2e05078f ! 1:  e7a8fbbe53c doc: git-rebase: start with an example
>       @@ Documentation/git-rebase.adoc: SYNOPSIS
>         DESCRIPTION
>         -----------
>        +Transplant a series of commits onto a different starting point.
>       ++You can also use `git rebase` to reorder or combine commits: see INTERACTIVE
>       ++MODE below for how to do that.
>        +
>        +For example, imagine that you have been working on the `topic` branch in this
>        +history, and you want to "catch up" to the work done on the `master` branch.
>       @@ Documentation/git-rebase.adoc: SYNOPSIS
>        +    D---E---F---G master
>        +------------
>        +
>       -+You can also use `git rebase` to reorder or combine commits: see INTERACTIVE
>       -+MODE below for how to do that.
>        +
>         If `<branch>` is specified, `git rebase` will perform an automatic
>         `git switch <branch>` before doing anything else.  Otherwise
>   2:  5459b7ff560 ! 2:  ad63f69918d doc: git rebase: dedup merge conflict discussion
>       @@ Commit message
>        
>         ## Documentation/git-rebase.adoc ##
>        @@ Documentation/git-rebase.adoc: shortcut for `git checkout topic && git rebase master`.
>       - You can also use `git rebase` to reorder or combine commits: see INTERACTIVE
>       - MODE below for how to do that.
>       + ------------
>       +
>         
>        +If there is a merge conflict during this process, `git rebase` will stop at the
>        +first problematic commit and leave conflict markers. If this happens, you can do
>   3:  948c205f1e6 = 3:  7ee6b0afe88 doc: git rebase: clarify arguments syntax
>   4:  e229b9fccb2 = 4:  4686417b28e doc: git-rebase: move --onto explanation down
>   5:  5ab235b067b ! 5:  9c7f2716bc8 doc: git-rebase: update discussion of internals
>       @@ Documentation/git-rebase.adoc: linkgit:git-config[1] for details) and the `--for
>        -`--onto` option was supplied.  This has the exact same effect as
>        -`git reset --hard <upstream>` (or `<newbase>`). `ORIG_HEAD` is set
>        -to point at the tip of the branch before the reset.
>       -+Here is a more detailed description of what `git rebase <upstream>` does:
>       ++Here is a simplified description of what `git rebase <upstream>` does:
>        +
>       -+1. Make a list of all commits in the current branch that are not in
>       -+   `<upstream>`. This is the same set of commits that would be shown by `git log
>       -+   <upstream>..HEAD`. You can use `--fork-point` or `--root` to change how this
>       -+   list of commits is constructed.
>       ++1. Make a list of all new commits on your current branch since it branched
>       ++   off from `<upstream>`. This is the same set of commits that would be shown
>       ++   by `git log  <upstream>..HEAD`. You can use `--fork-point` or  `--root` to
>       ++   change how this list of commits is constructed.
>        +2. Check whether any of those commits are duplicates of commits already
>       -+   in `<upstream>`, remove them from the list, and print out a warning about
>       -+   each removed commit. You can use `--reapply-cherry-picks` to include
>       -+   duplicate commits.
>       -+3. Check out `<upstream>` (or `<newbase>` if the `--onto` option was
>       -+   supplied) with the equivalent of `git checkout --detach <upstream>`.
>       ++   in `<upstream>` and remove them from the list.
>       ++3. Check out `<upstream>` with the equivalent of `git checkout --detach <upstream>`.
>        +4. Replay the commits, one by one, in order. This is similar to running
>        +   `git cherry-pick <commit>` for each commit. See REBASING MERGES for how merges
>        +   are handled.
>        +5. Update your branch to point to the final commit with the equivalent
>       -+   of `git switch -C <branch>`.
>       ++   of `git checkout -C <branch>`.
>         
>         [NOTE]
>        -`ORIG_HEAD` is not guaranteed to still point to the previous branch tip
>