On 15/08/2025 17:52, Julia Evans via GitGitGadget wrote:
Combine point 1 and 2 in "a simplified description of what git rebase
<upstream> does:" into a shorter summary.
This looks great, I've left a couple of comments in reply to Junio but
I'd be happy enough to see this merged as-is.
I'm going to be off the list for a week from tomorrow so I wont be
commenting any more this week.
Thanks for working on this
Phillip
Julia Evans (5):
doc: git-rebase: start with an example
doc: git rebase: dedup merge conflict discussion
doc: git rebase: clarify arguments syntax
doc: git-rebase: move --onto explanation down
doc: git-rebase: update discussion of internals
Documentation/git-rebase.adoc | 298 +++++++++++++++-------------------
1 file changed, 133 insertions(+), 165 deletions(-)
base-commit: 2c2ba49d55ff26c1082b8137b1ec5eeccb4337d1
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1949%2Fjvns%2Fclarify-rebase-v8
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1949/jvns/clarify-rebase-v8
Pull-Request: https://github.com/gitgitgadget/git/pull/1949
Range-diff vs v7:
1: e7a8fbbe53c = 1: e7a8fbbe53c doc: git-rebase: start with an example
2: ad63f69918d = 2: ad63f69918d doc: git rebase: dedup merge conflict discussion
3: 7ee6b0afe88 = 3: 7ee6b0afe88 doc: git rebase: clarify arguments syntax
4: 4686417b28e = 4: 4686417b28e doc: git-rebase: move --onto explanation down
5: 79f29ad1e68 ! 5: cb85642bb9d doc: git-rebase: update discussion of internals
@@ Documentation/git-rebase.adoc: linkgit:git-config[1] for details) and the `--for
-to point at the tip of the branch before the reset.
+Here is a simplified description of what `git rebase <upstream>` does:
+
-+1. Make a list of all new commits on your current branch since it branched
-+ off from `<upstream>`. This is the same set of commits that would be shown
-+ by `git log <upstream>..HEAD`. You can use `--fork-point` or `--root` to
-+ change how this list of commits is constructed.
-+2. Check whether any of those commits contain the same changes (according to
-+ `git patch-id`) as a commit already in `<upstream>` and remove them from
-+ the list.
-+3. Check out `<upstream>` with the equivalent of
++1. Make a list of all commits on your current branch since it branched
++ off from `<upstream>` that do not have an equivalent commit in
++ `<upstream>`.
++2. Check out `<upstream>` with the equivalent of
+ `git checkout --detach <upstream>`.
-+4. Replay the commits, one by one, in order. This is similar to running
++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.
-+5. Update your branch to point to the final commit with the equivalent
++4. Update your branch to point to the final commit with the equivalent
+ of `git checkout -B <branch>`.
[NOTE]
