On Fri, Aug 8, 2025, at 12:30 PM, Junio C Hamano wrote: > "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. I'm very happy to hear that feedback: I thought it was very dry as well, but I copied that part from elsewhere in the man page because I thought that was git's preferred documentation style. I'll work on making it less dry. > 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. That's actually in PATCH 3/5 of this series: I also thought the explanation that the form being a shorthand for checkout followed by rebase was extremely clear so I moved it to be the primary explanation of what `git rebase <upstream> <branch>` does.
