> Would it make sense to convert this into a bulleted list to further
> highlight this multi-step process?
I like this idea. I think we can combine this with Phillip's point about
"--reapply-cherry-picks" to expand the list a little more and remove the
paragraph at the end about how duplicate commits are skipped. ("If the upstream
branch already contains a change you have made...") I think probably the diagram
can be removed too, I'm not sure how much value it's adding.
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.
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>`.
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>`.
I imagine actually #1 and #2 happen concurrently, but I split them up because
it felt unwieldy to explain them both the same point.
>
>> [NOTE]
>> +`ORIG_HEAD` is set to point at the tip of the branch before the rebase.
>> `ORIG_HEAD` is not guaranteed to still point to the previous branch tip
>> at the end of the rebase if other commands that write that pseudo-ref
>> (e.g. `git reset`) are used during the rebase. The previous branch tip,
>> however, is accessible using the reflog of the current branch
>> (i.e. `@{1}`, see linkgit:gitrevisions[7]).
>
> This information feels somewhat contradictory. Should we maybe say
> something like this:
>
> When starting the rebase, `ORIG_HEAD` is set to point to at the tip
> of the to-be-rebased branch. As `ORIG_HEAD` may be modified by
> various operations during the rebase, it is not guaranteed to still
> point to this branch at the end of the rebase. The previous branch
> tip, however, is accessible using the reflog of the current branch
> (i.e. `@{1}`, see linkgit:gitrevisions[7]).
>
> Note that I'm also dropping the reference to "pseudo-ref". ORIG_HEAD is
> not a pseudo-ref, as we have clarified in 6fd8037564
> (Documentation/glossary: redefine pseudorefs as special refs,
> 2024-05-15).
I like that! Also very happy to remove the word "pseudo-ref".
- Julia
