From: Phillip Wood Date: Wed, 13 Aug 2025 13:31:32 GMT Subject: Re: [PATCH v6 0/5] doc: git-rebase: clarify DESCRIPTION section Message-ID: <52504ef0-7d4c-4298-af11-10477673e9d0@gmail.com> In-Reply-To: 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 `` is specified, `git rebase` will perform an automatic > `git switch ` 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 ` (or ``). `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 ` does: > ++Here is a simplified description of what `git rebase ` does: > + > -+1. Make a list of all commits in the current branch that are not in > -+ ``. This is the same set of commits that would be shown by `git log > -+ ..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 ``. This is the same set of commits that would be shown > ++ by `git log ..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 ``, 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 `` (or `` if the `--onto` option was > -+ supplied) with the equivalent of `git checkout --detach `. > ++ in `` and remove them from the list. > ++3. Check out `` with the equivalent of `git checkout --detach `. > +4. 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. > +5. Update your branch to point to the final commit with the equivalent > -+ of `git switch -C `. > ++ of `git checkout -C `. > > [NOTE] > -`ORIG_HEAD` is not guaranteed to still point to the previous branch tip >