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

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> +Here is a simplified description of what `git rebase <upstream>` does:

Now this is a "this is roughly how it works", we can afford to give
a simplified picture that may not exactly match the implementation,
which is great freedom to have while writing documentation for first
time users.

> +1. Make a list of all new commits on your current branch since it branched
> +   off from `<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>` and remove them from the list.

So, I do not mind #2 described as a separate step.  Conceptually, it
is between "create a list of all commits in the range and filter out
what have already been applied" and "create a list of all commits
that are not in the upstream yet".  We may be able to rephrase "all
new commits on your current branch" somewhat to make it unnecessary
to describe #2, though.  If we are willing to stop talking about
"This is the same set of ...", then the description becomes very
simple:

    Make a list of all commits on your current branch since it
    branched off from `<upstream>` that do not have equivalent
    change in `<upstream>`.

> +3. Check out `<upstream>` with the equivalent of `git checkout --detach <upstream>`.

The line is getting overly long here and a few lines below.  If your
editor has the feature, tell it to auto-wrap at around 66-72 column.

> +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 checkout -C <branch>`.

Force-create-branch while checking out is `git checkout -B
<branch>`, not -C.