Re: [PATCH v4 5/5] doc: git-rebase: update discussion of internals

From: Julia Evans <julia@jvns.ca>
Date: Aug 11, 2025, 19:34 UTC
Message-ID: <2c9d7fe5-4026-4143-9c56-f5c56f4634f3@app.fastmail.com>
In-Reply-To: <aJmt1fv66bO_ZMpI@pks.im>

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

Show 23 quoted lines

>
>>  [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