On 10 April 2018 at 14:30, Johannes Schindelin <johannes.schindelin@xxxxxx> wrote: > The --rebase-merges mode is probably not half as intuitive to use as > its inventor hopes, so let's document it some. I quite like this documentation. Well-structured and well-paced. Already after the first reading, I believe I understand how to use this. > +The `label` command puts a label to whatever will be the current > +revision when that command is executed. Internally, these labels are > +worktree-local refs that will be deleted when the rebase finishes or > +when it is aborted. That way, rebase operations in multiple worktrees > +linked to the same repository do not interfere with one another. In the above paragraph, you say "internally". > +At this time, the `merge` command will *always* use the `recursive` > +merge strategy, with no way to choose a different one. To work around > +this, an `exec` command can be used to call `git merge` explicitly, > +using the fact that the labels are worktree-local refs (the ref > +`refs/rewritten/onto` would correspond to the label `onto`). This sort of encourages use of that "internal" detail, which made me a little bit surprised at first. But if we can't come up with a reason why we would want to change the "refs/rewritten/<label>"-concept later (I can't) and if we think the gain this paragraph gives is significant (it basically gives access to `git merge` in its entirety), then providing this hint might be the correct thing to do. > +Note: the first command (`reset onto`) labels the revision onto which > +the commits are rebased; The name `onto` is just a convention, as a nod > +to the `--onto` option. s/reset onto/label onto/ Martin
