Re: [PATCH v4 1/5] doc: git-rebase: start with an example
From: Phillip Wood <hidden>
Date: 2025-08-10 15:41:51
Hi Julia On 09/08/2025 02:14, Julia Evans via GitGitGadget wrote:
From: Julia Evans <redacted> 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.
This is a very welcome improvement which makes it clear what rebasing a branch does. There are other important uses of rebase such as rearranging commits and squashing fixup commits that it would be nice to mention early on in the man page as well. Those do not necessarily change the base of the branch. I wonder if we could add a sentence about that which links to the INTERACTIVE MODE section. Thanks Phillip
quoted hunk ↗ jump to hunk
Signed-off-by: Julia Evans <redacted> --- Documentation/git-rebase.adoc | 49 ++++++++++++++++------------------- 1 file changed, 23 insertions(+), 26 deletions(-)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. + +For example, imagine that you have been working on the `topic` branch in this +history, and you want to "catch up" to the work done on the `master` branch. + +------------ + A---B---C topic + / + D---E---F---G master +------------ + +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 this +by running `git rebase master` while the `topic` branch is checked out. If you +want to rebase `topic` while on another branch, `git rebase master topic` is a +shortcut for `git checkout topic && git rebase master`. + +------------ + 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 +81,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