"Julia Evans via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes:
> From: Julia Evans <julia@xxxxxxx>
>
> Start with an example that mirrors the example in the `git-merge` man
> page, to make it easier for folks to understand the difference between a
> rebase and a merge.
>
> Signed-off-by: Julia Evans <julia@xxxxxxx>
> ---
> Documentation/git-rebase.adoc | 46 +++++++++++++++--------------------
> 1 file changed, 20 insertions(+), 26 deletions(-)
>
> diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
> index 956d3048f5a6..fee73623990d 100644
> --- a/Documentation/git-rebase.adoc
> +++ b/Documentation/git-rebase.adoc
> @@ -16,6 +16,26 @@ SYNOPSIS
>
> DESCRIPTION
> -----------
> +Transplant a series of commits onto a different starting point.
It is an excellent idea to start with what it does, before
explaining how you would drive it.
> +For example, assume the following history exists and the current branch is `topic`:
The line is a bit overly long, and the style a bit on the
"description of dry facts" side, which might want to give
a bit more "motivation" to help readers.
Here is my attempt.
Imagine that you have been working on the `topic` branch in this
history, and you'd want to "catch up" to the work done on the
`master` branch.
*** Illustration of "before" state ***
You want to transplant the commits you made on `topic` since it
diverged from `master` (i.e. A, B, and C), on top of the current
`master`. You can do so by running `git rebase master` while the
`topic` branch is checked out. `git rebase master topic` works
as a short-cut to `git checkout topic && git rebase master`.
*** Illustration of "after" state ***
perhaps?
Note that you lost the mention of `git rebase master topic` syntax
and the explanation that the form being a shorthand for checkout
followed by rebase, which I do not think appear anywhere else in the
document, so my suggested rewrite above resurrects it.
> +------------
> + A---B---C topic
> + /
> + D---E---F---G master
> +------------
> +
> +Then `git rebase master` will find all of the commits since `topic` diverged
> +from `master` and copy the changes in each of those commits on top of the
> +`master` branch.
> +
> +------------
> + A'--B'--C' topic
> + /
> + D---E---F---G master
> +------------
> +
> If `<branch>` is specified, `git rebase` will perform an automatic
> `git switch <branch>` before doing anything else. Otherwise
> it remains on the current branch.
> @@ -58,32 +78,6 @@ that caused the merge failure with `git rebase --skip`. To check out the
> original `<branch>` and remove the `.git/rebase-apply` working files, use
> the command `git rebase --abort` instead.
>
> -Assume the following history exists and the current branch is "topic":
> -
> -------------
> - A---B---C topic
> - /
> - D---E---F---G master
> -------------
> -
> -From this point, the result of either of the following commands:
> -
> -
> - git rebase master
> - git rebase master topic
> -
> -would be:
> -
> -------------
> - A'--B'--C' topic
> - /
> - D---E---F---G master
> -------------
> -
> -*NOTE:* The latter form is just a short-hand of `git checkout topic`
> -followed by `git rebase master`. When rebase exits `topic` will
> -remain the checked-out branch.
> -
> If the upstream branch already contains a change you have made (e.g.,
> because you mailed a patch which was applied upstream), then that commit
> will be skipped and warnings will be issued (if the 'merge' backend is
