Interactive rebase doc (Was: Leveraging --rebase-merges --update-refs mechanism to rebase several branches in one run)

[Yann Dirson <ydirson@free.fr>]

> Johannes Sixt wrote:
> > Am 06.01.24 um 20:05 schrieb Yann Dirson:
> > > The "core + 1 variant" case pretty much works out of the box,
> > > with
> > > --rebase-merges
> > > and --update-refs generating a perfect instructions sheet.
> > > 
> > > But if I was to rebase just one variant while rewriting the core
> > > branch, obviously
> > > all other variants would still fork off the pre-rewrite core
> > > branch, and we'd loose
> > > all chances of automating the same work on the other variants.
> > > 
> > > OTOH, if I get `git-rebase` to generate the instruction sheets
> > > for
> > > those other
> > > variants first, strip them (manually) from the common part, and
> > > insert them in the
> > > instruction sheet of my "core + 1 variant" case ... I do get the
> > > whole of my branches
> > > rebased together, and sharing the updated core.
> > 
> > Not a complete automation, but... You can merge all variant
> > branches
> > into a temporary branch (or detached HEAD), even if that are merely
> > -s
> > ours merges, and then rebase the temporary branch with
> > --rebase-merges
> > --update-refs. This will generate the instruction sheet that you
> > want.
> > You can remove the final merge instructions (the temporary ones)
> > from
> > the instruction sheet if you do not want them to be executed.
> 
> Nice idea, and this is indeed automatable for the most part, Q&D PoC
> below.
> 
> There are a few things I can see missing in this PoC:
> 
> - removal of the final merge from instruction sheet
> 
>   Could be done by wrapping $EDITOR - I'm not particularly fond doing
>   things
>   behind the user's back, but I lack better ideas.
> 
> - restoration of HEAD
> 
>   In the general case it cannot be done from the script, so we would
>   naturally
>   want to do that from the instruction sheet?
> 
>   While I was at manually removing the final merge, I experimented
>   with changing
>   the "reset onto" to "reset <a branch name>", but that resulted in
>   moving HEAD
>   to the pre-rebase version of the requested branch.

Related to this, I turned to the rebase manpage to get reference
information about update-ref, but I could not find anything about it:
only --update-refs is described, but this description also only seems to
address the non-interactive behavior.

In fact:
- there does not appear to be a reference to the interactive
instruction sheet in the rebase doc, only in the default template
- --interactive only directs the user to "Splitting commits", not to
"interactive mode"
- the "interactive mode" section really looks more like a didactic intro
to interactive rebase than like a reference doc

Would it seem OK to change things as follows?

- move current "interactive mode", "splitting commits", and "rebasing merges"
contents into a new gitrebase(7) guide
- leave in git-rebase(1) only an "interactive mode" with the reference doc
for the instruction sheet, and a pointer to the guide for detailed walkthrough
- selectively move back a few things like --strategy paragraph from
"rebasing merges"

Best regards,
-- 
Yann