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 <julia@jvns.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Julia Evans
2025-08-23 00:43:02 +00:00
committed by Junio C Hamano
parent 981ce57389
commit 3f7f2b0359

View File

@@ -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 assumed. If you are currently not on any branch or if the current
branch does not have a configured upstream, the rebase will abort. 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 simplified description of what `git rebase <upstream>` does:
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 1. Make a list of all commits on your current branch since it branched
`--onto` option was supplied. This has the exact same effect as off from `<upstream>` that do not have an equivalent commit in
`git reset --hard <upstream>` (or `<newbase>`). `ORIG_HEAD` is set `<upstream>`.
to point at the tip of the branch before the reset. 2. Check out `<upstream>` with the equivalent of
`git checkout --detach <upstream>`.
3. Replay the commits, one by one, in order. This is similar to running
`git cherry-pick <commit>` 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 <branch>`.
[NOTE] [NOTE]
`ORIG_HEAD` is not guaranteed to still point to the previous branch tip When starting the rebase, `ORIG_HEAD` is set to point to the commit at the tip
at the end of the rebase if other commands that write that pseudo-ref of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still
(e.g. `git reset`) are used during the rebase. The previous branch tip, point to that commit at the end of the rebase if other commands that change
however, is accessible using the reflog of the current branch `ORIG_HEAD` (like `git reset`) are used during the rebase. The previous branch
(i.e. `@{1}`, see linkgit:gitrevisions[7]). 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..<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
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
------------
TRANSPLANTING A TOPIC BRANCH WITH --ONTO TRANSPLANTING A TOPIC BRANCH WITH --ONTO
---------------------------------------- ----------------------------------------