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

[Patrick Steinhardt <ps@pks.im>]

On Sat, Aug 09, 2025 at 01:14:17AM +0000, Julia Evans via GitGitGadget wrote:
> diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
> index 50c84f138212..c16ee37b46a7 100644
> --- a/Documentation/git-rebase.adoc
> +++ b/Documentation/git-rebase.adoc
> @@ -65,31 +65,31 @@ linkgit:git-config[1] for details) and the `--fork-point` option is
>  assumed.  If you are currently not on any branch or if the current
>  branch does not have a configured upstream, the rebase will abort.
>  
> -All changes made by commits in the current branch but that are not
> -in `<upstream>` are saved to a temporary area.  This is the same set
> -of commits that would be shown by `git log <upstream>..HEAD`; or by
> -`git log 'fork_point'..HEAD`, if `--fork-point` is active (see the
> -description on `--fork-point` below); or by `git log HEAD`, if the
> -`--root` option is specified.
> -
> -The current branch is reset to `<upstream>` or `<newbase>` if the
> -`--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:
> +
> +First, it makes 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.
> +
> +Then it checks out `<upstream>` (or `<newbase>` if the `--onto` option was
> +supplied) with the equivalent of `git switch --detach <upstream>`.
> +
> +Then it replays 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.
> +
> +Finally, it updates your branch to point to the final commit with the equivalent
> +of `git switch -C <branch>`.

Would it make sense to convert this into a bulleted list to further
highlight this multi-step process?

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

Patrick