Re: [PATCH v6 15/15] rebase -i --rebase-merges: add a section to the man page

From: Martin Ågren <martin.agren@gmail.com>
Date: Apr 10, 2018, 18:49 UTC
Message-ID: <CAN0heSrSvKiRGxSS0jq9Hsxkc7NSuZkt+gLD7DhXRjkfNJd_hw@mail.gmail.com>
In-Reply-To: <a162afa761e3000eb60169fce7a50938888f80b4.1523362469.git.johannes.schindelin@gmx.de>

On 10 April 2018 at 14:30, Johannes Schindelin <johannes.schindelin@gmx.de> 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.

Show 5 quoted lines

> +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".

Show 5 quoted lines

> +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