From ea1438e094e950d75196fdab79e22c174251bb66 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 6 Aug 2025 15:53:47 -0400 Subject: [PATCH 1/5] doc: git-rebase: start with an example - 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. - Mention that rebase can combine or reorder commits Signed-off-by: Julia Evans --- Documentation/git-rebase.adoc | 52 +++++++++++++++++------------------ 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index 956d3048f5a618..bb5a3ff7f82860 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -16,6 +16,32 @@ SYNOPSIS DESCRIPTION ----------- +Transplant a series of commits onto a different starting point. +You can also use `git rebase` to reorder or combine commits: see INTERACTIVE +MODE below for how to do that. + +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 `` is specified, `git rebase` will perform an automatic `git switch ` before doing anything else. Otherwise it remains on the current branch. @@ -58,32 +84,6 @@ that caused the merge failure with `git rebase --skip`. To check out the original `` 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 From 339b7a1bc5be0fe3fd56c03c49e4c578d04c33d0 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 6 Aug 2025 15:56:08 -0400 Subject: [PATCH 2/5] doc: git rebase: dedup merge conflict discussion Previously there were two explanations, this combines them both into a single explanation. Signed-off-by: Julia Evans --- Documentation/git-rebase.adoc | 49 ++++++++++++++--------------------- 1 file changed, 20 insertions(+), 29 deletions(-) diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index bb5a3ff7f82860..e82ceb9cbfcefa 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -42,6 +42,26 @@ shortcut for `git checkout topic && git rebase master`. ------------ +If there is a merge conflict during this process, `git rebase` will stop at the +first problematic commit and leave conflict markers. If this happens, you can do +one of these things: + +1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<) + and make edits to resolve the conflict. For each file you edit, you need to + tell Git that the conflict has been resolved. You can mark the conflict as + resolved with `git add `. After resolving all of the conflicts, + you can continue the rebasing process with + + git rebase --continue + +2. Stop the `git rebase` and return your branch to its original state with + + git rebase --abort + +3. Skip the commit that caused the merge conflict with + + git rebase --skip + If `` is specified, `git rebase` will perform an automatic `git switch ` before doing anything else. Otherwise it remains on the current branch. @@ -77,13 +97,6 @@ any commits in `HEAD` which introduce the same textual changes as a commit in `HEAD..` are omitted (i.e., a patch already accepted upstream with a different commit message or timestamp will be skipped). -It is possible that a merge failure will prevent this process from being -completely automatic. You will have to resolve any such merge failure -and run `git rebase --continue`. Another option is to bypass the commit -that caused the merge failure with `git rebase --skip`. To check out the -original `` and remove the `.git/rebase-apply` working files, use -the command `git rebase --abort` instead. - 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 @@ -186,28 +199,6 @@ This is useful if F and G were flawed in some way, or should not be part of topicA. Note that the argument to `--onto` and the `` parameter can be any valid commit-ish. -In case of conflict, `git rebase` will stop at the first problematic commit -and leave conflict markers in the tree. You can use `git diff` to locate -the markers (<<<<<<) and make edits to resolve the conflict. For each -file you edit, you need to tell Git that the conflict has been resolved, -typically this would be done with - - - git add - - -After resolving the conflict manually and updating the index with the -desired resolution, you can continue the rebasing process with - - - git rebase --continue - - -Alternatively, you can undo the 'git rebase' with - - - git rebase --abort - MODE OPTIONS ------------ From f42c2c794a96c9a2dcb34bd7fe7b202466b3ffe0 Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 6 Aug 2025 16:00:37 -0400 Subject: [PATCH 3/5] doc: git rebase: clarify arguments syntax Remove duplicate explanation of `git rebase ` which is already explained above. Signed-off-by: Julia Evans --- Documentation/git-rebase.adoc | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index e82ceb9cbfcefa..6d02648a9b3cee 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -62,11 +62,7 @@ one of these things: git rebase --skip -If `` is specified, `git rebase` will perform an automatic -`git switch ` before doing anything else. Otherwise -it remains on the current branch. - -If `` is not specified, the upstream configured in +If you don't specify an `` to rebase onto, the upstream configured in `branch..remote` and `branch..merge` options will be used (see linkgit:git-config[1] for details) and the `--fork-point` option is assumed. If you are currently not on any branch or if the current From 9c2a54ab9fa9b3dea47f4ab366fc5ff7c8946a3f Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 6 Aug 2025 16:06:01 -0400 Subject: [PATCH 4/5] doc: git-rebase: move --onto explanation down There's a very clear explanation with examples of using --onto which is currently buried in the very long DESCRIPTION section. This moves it to its own section, so that we can reference the explanation from the `--onto` option by name. Signed-off-by: Julia Evans --- Documentation/git-rebase.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index 6d02648a9b3cee..b3354e0e4f82e9 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -114,6 +114,9 @@ will result in: D---E---A'---F master ------------ +TRANSPLANTING A TOPIC BRANCH WITH --ONTO +---------------------------------------- + Here is how you would transplant a topic branch based on one branch to another, to pretend that you forked the topic branch from the latter branch, using `rebase --onto`. @@ -240,6 +243,8 @@ As a special case, you may use "A\...B" as a shortcut for the merge base of A and B if there is exactly one merge base. You can leave out at most one of A and B, in which case it defaults to HEAD. +See TRANSPLANTING A TOPIC BRANCH WITH --ONTO above for examples. + --keep-base:: Set the starting point at which to create the new commits to the merge base of `` and ``. Running From 5a1dd8df29baf68c780d76880a5eb586e20102fa Mon Sep 17 00:00:00 2001 From: Julia Evans Date: Wed, 6 Aug 2025 22:21:10 -0400 Subject: [PATCH 5/5] doc: git-rebase: update discussion of internals - make it clearer that we're talking about a multistep process - give a more technically accurate description how rebase works with the merge backend. - condense the explanation of how git rebase skips commits with the same textual changes into a single bullet point and remove the explanatory diagram. Lots of things which are more complicated are already being explained without a diagram. - remove the explanation of how exactly `--fork-point` and `--root` work since that information is in the OPTIONS section - put all discussion of `ORIG_HEAD` inside the note Signed-off-by: Julia Evans --- Documentation/git-rebase.adoc | 61 +++++++++++------------------------ 1 file changed, 18 insertions(+), 43 deletions(-) diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc index b3354e0e4f82e9..d2f760af68666b 100644 --- a/Documentation/git-rebase.adoc +++ b/Documentation/git-rebase.adoc @@ -68,51 +68,26 @@ linkgit:git-config[1] for details) and the `--fork-point` option is assumed. If you are currently not on any branch or if the current branch does not have a configured upstream, the rebase will abort. -All changes made by commits in the current branch but that are not -in `` are saved to a temporary area. This is the same set -of commits that would be shown by `git log ..HEAD`; or by -`git log 'fork_point'..HEAD`, if `--fork-point` is active (see the -description on `--fork-point` below); or by `git log HEAD`, if the -`--root` option is specified. - -The current branch is reset to `` or `` if the -`--onto` option was supplied. This has the exact same effect as -`git reset --hard ` (or ``). `ORIG_HEAD` is set -to point at the tip of the branch before the reset. +Here is a simplified description of what `git rebase ` does: + +1. Make a list of all commits on your current branch since it branched + off from `` that do not have an equivalent commit in + ``. +2. Check out `` with the equivalent of + `git checkout --detach `. +3. Replay the commits, one by one, in order. This is similar to running + `git cherry-pick ` for each commit. See REBASING MERGES for how merges + are handled. +4. Update your branch to point to the final commit with the equivalent + of `git checkout -B `. [NOTE] -`ORIG_HEAD` is not guaranteed to still point to the previous branch tip -at the end of the rebase if other commands that write that pseudo-ref -(e.g. `git reset`) are used during the rebase. The previous branch tip, -however, is accessible using the reflog of the current branch -(i.e. `@{1}`, see linkgit:gitrevisions[7]). - -The commits that were previously saved into the temporary area are -then reapplied to the current branch, one by one, in order. Note that -any commits in `HEAD` which introduce the same textual changes as a commit -in `HEAD..` are omitted (i.e., a patch already accepted upstream -with a different commit message or timestamp will be skipped). - -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 -used). For example, running `git rebase master` on the following -history (in which `A'` and `A` introduce the same set of changes, but -have different committer information): - ------------- - A---B---C topic - / - D---E---A'---F master ------------- - -will result in: - ------------- - B'---C' topic - / - D---E---A'---F master ------------- +When starting the rebase, `ORIG_HEAD` is set to point to the commit at the tip +of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still +point to that commit at the end of the rebase if other commands that change +`ORIG_HEAD` (like `git reset`) are used during the rebase. The previous branch +tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`, +see linkgit:gitrevisions[7]. TRANSPLANTING A TOPIC BRANCH WITH --ONTO ----------------------------------------