[PATCH 5/5] doc: git-rebase: update discussion of internals
From: Julia Evans via GitGitGadget <hidden>
Date: 2025-08-08 15:24:32
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
From: Julia Evans <redacted> - make it clearer that we're talking about three steps of a process - delete a duplicate explanation of how git rebase skips commits with the same textual changes (it's explained in more detail a few lines further down) - move the `ORIG_HEAD` note down so that it doesn't interrupt the discussion of the mechanics. Signed-off-by: Julia Evans <redacted> --- Documentation/git-rebase.adoc | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
index c63d67f340a0..6b79cd0daca9 100644
--- a/Documentation/git-rebase.adoc
+++ b/Documentation/git-rebase.adoc@@ -67,18 +67,23 @@ 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 +Here is a more detailed description of what `git rebase <upstream>` does: + +First, all changes made by commits in the current branch but that are not in `<upstream>` are saved to a temporary area. This is the same set of commits that would be shown by `git log <upstream>..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 `<upstream>` or `<newbase>` if the +Then the current branch is reset to `<upstream>` or `<newbase>` if the `--onto` option was supplied. This has the exact same effect as `git reset --hard <upstream>` (or `<newbase>`). `ORIG_HEAD` is set to point at the tip of the branch before the reset. +Then the commits that were previously saved into the temporary area are +reapplied to the current branch, one by one, in order. + [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
@@ -86,12 +91,6 @@ at the end of the rebase if other commands that write that pseudo-ref 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..<upstream>` 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
--
gitgitgadget