Thread (76 messages) 76 messages, 6 authors, 2025-08-23

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
Keyboard shortcuts
hback out one level
jnext message in thread
kprevious message in thread
ldrill in
Escclose help / fold thread tree
?toggle this help