Hi Julia
On 11/08/2025 22:51, Julia Evans via GitGitGadget wrote:
* move "You can also use git rebase to reorder or combine commits:" to the
beginning
Great
* replace "detailed description" with "simplified description" -- I thought
that I could write something that was relatively readable and also
accurate, but as usual Git has proven me wrong :). I tried to leave in
the details that I think seem relevant to using git: for example git
checkout --detach is relevant because it explains why git reflog works
well after a rebase.
* replace the git switch with git checkout that I'd missed previously
I didn't use the git log --cherry-pick option in the explanation because I
had personally never heard of that option before today, and I don't want
people to have to read the git log man page to be able to understand the
explanation. I also left out --reapply-cherry-picks just because I don't
understand the use case so I couldn't evaluate how likely it is to be
relevant to the person reading.
The use case for --reapply-cherry-picks is mostly that it is faster to
try picking a commit and then drop it if it results in a empty change
than it is to do the patch-id comparisons to avoid picking the commit in
the first place. This is especially true on partial clones where the
cherry-pick detection is really slow. I'm happy to leave it out but I
wonder if we should drop the references to --fork-point and --root as
well given they're also both pretty niche. I'd also be very happy to go
with Junio's suggestion to replace steps 1 & 2 with a general
description that does not mention 'git log' at all.
Thanks
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 | 302 +++++++++++++++-------------------
1 file changed, 136 insertions(+), 166 deletions(-)
base-commit: 2c2ba49d55ff26c1082b8137b1ec5eeccb4337d1
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1949%2Fjvns%2Fclarify-rebase-v6
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1949/jvns/clarify-rebase-v6
Pull-Request: https://github.com/gitgitgadget/git/pull/1949
Range-diff vs v5:
1: c2f2e05078f ! 1: e7a8fbbe53c doc: git-rebase: start with an example
@@ Documentation/git-rebase.adoc: 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.
@@ Documentation/git-rebase.adoc: SYNOPSIS
+ D---E---F---G master
+------------
+
-+You can also use `git rebase` to reorder or combine commits: see INTERACTIVE
-+MODE below for how to do that.
+
If `<branch>` is specified, `git rebase` will perform an automatic
`git switch <branch>` before doing anything else. Otherwise
2: 5459b7ff560 ! 2: ad63f69918d doc: git rebase: dedup merge conflict discussion
@@ Commit message
## Documentation/git-rebase.adoc ##
@@ Documentation/git-rebase.adoc: shortcut for `git checkout topic && git rebase master`.
- You can also use `git rebase` to reorder or combine commits: see INTERACTIVE
- MODE below for how to do that.
+ ------------
+
+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
3: 948c205f1e6 = 3: 7ee6b0afe88 doc: git rebase: clarify arguments syntax
4: e229b9fccb2 = 4: 4686417b28e doc: git-rebase: move --onto explanation down
5: 5ab235b067b ! 5: 9c7f2716bc8 doc: git-rebase: update discussion of internals
@@ Documentation/git-rebase.adoc: linkgit:git-config[1] for details) and the `--for
-`--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.
-+Here is a more detailed description of what `git rebase <upstream>` does:
++Here is a simplified description of what `git rebase <upstream>` does:
+
-+1. Make a list of all commits in the current branch that are not in
-+ `<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.
++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 are duplicates of commits already
-+ in `<upstream>`, remove them from the list, and print out a warning about
-+ each removed commit. You can use `--reapply-cherry-picks` to include
-+ duplicate commits.
-+3. Check out `<upstream>` (or `<newbase>` if the `--onto` option was
-+ supplied) with the equivalent of `git checkout --detach <upstream>`.
++ in `<upstream>` and remove them from the list.
++3. 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
+ `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
-+ of `git switch -C <branch>`.
++ of `git checkout -C <branch>`.
[NOTE]
-`ORIG_HEAD` is not guaranteed to still point to the previous branch tip
