Re: [PATCH v4 1/5] doc: git-rebase: start with an example

[Patrick Steinhardt <ps@pks.im>]

On Sat, Aug 09, 2025 at 01:14:13AM +0000, Julia Evans via GitGitGadget wrote:
> From: Julia Evans <julia@jvns.ca>
> 
> 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.

Makes sense.

> diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
> index 956d3048f5a6..449f01fba560 100644
> --- a/Documentation/git-rebase.adoc
> +++ b/Documentation/git-rebase.adoc
> @@ -16,6 +16,29 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> +Transplant a series of commits onto a different starting point.

Nit: while this is one use case for git-rebase(1), I'd claim that
nowadays with interactive rebases there's the other use case where we
don't change the starting point but only edit the range of commits
itself.

So how about this instead:

    Edit a series of commits and optionally transplant it onto a
    different starting point.

We could also make the two different modes a bit more explicit by
pointing out both different use cases directly.

If you agree then we should probably also modernize the description in
the NAME section accordingly.

Patrick