Re: [PATCH v4 5/5] doc: git-rebase: update discussion of internals
From: Julia Evans <hidden>
Date: 2025-08-11 19:34:22
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.
quoted
[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