From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Tue, 30 Jun 2026 09:44:47 GMT
Subject: Re: [PATCH v4 3/3] replay: offer an option to linearize the commit topology
Message-ID: <9e7d14c4-82f0-2b89-b07b-f219119a199b@gmx.de>
In-Reply-To: <akInDBlyWbbRFcLH@pks.im>

Hi Patrick & Toon,

On Tue, 30 Jun 2026, Patrick Steinhardt wrote:

> On Fri, Jun 26, 2026 at 07:36:31AM +0200, Toon Claes wrote:
> > Patrick Steinhardt <ps@pks.im> writes:
> > 
> > > git-rebase(1) essentially knows about three different modes:
> > >
> > >   - "--no-rebase-merges", which is the default and maps to your
> > >     "--linearize".
> > >
> > >   - "--rebase-merges", which by default doesn't rebase cousins by using
> > >     "--ancestry-path" internally.
> > >
> > >   - "--rebase-merges=rebase-cousins", which doesn't pass the above
> > >     option.
> > >
> > > So it's not a simple boolean there, which makes me wonder whether we
> > > should mirror the same interface so that all of git-rebase(1)'s modes
> > > can be represented, as well.
> > 
> > That's a valid question, although I don't know a good answer to that.
> > 
> > Basically you're asking for what the command line options will look
> > like? Allow me to think out loud.
> > 
> > In this series I'm adding --linearize to git-replay(1). As mentioned, I
> > don't think it makes sense to add it to git-history(1) as well. Without
> > this option, the process aborts when it encounters a merge.
> > 
> > Dscho sent a patch series to properly replay (2-way) merges. I think
> > this should become the default for both git-replay(1) and
> > git-history(1).
> > 
> > But then, do we want to have an option that brings back the current
> > behavior of aborting at merges? Maybe with --no-merges?
> 
> I think that would be a sensible option to have.

I also think that we'll need a way to abort at merges because linearizing
commits is a relatively common operation.

> > Then there's the option of rebasing cousins left. That's something that
> > isn't covered by Dscho's series yet. Maybe --replay-cousins?
> > 
> > To reiterate what the final design could look like:
> > 
> >  * <nothing>: replay merges preserving topology.
> >  * "--linearize": flattens merges (only git-replay(1)).
> >  * "--no-merges": dies when the process tries to replay a merge.
> >  * "--replay-cousins": does what --rebase-merges=rebase-cousins does.
> 
> Right. And if we tried to be consistent with git-rebase(1), then this
> could be done as:
> 
>   - "--rebase-merges" to replay merges preserving topology, which is the
>     default once we support replaying them.
> 
>   - "--no-rebase-merges" to flatten commits.
> 
>   - "--rebase-merges=abort" to explicitly die when seeing merges.
> 
>   - "--rebase-merges=rebase-cousins"

The `git rebase` options are unlikely to be a good precedent to follow.
Their history is full of usability warts, and in hindsight, I would really
have loved a more steady hand in developing and maintaining a good UX. The
fact alone that this is called `rebase` speaks volumes about how hostile
of a user experience this command surfaces.

In any case, these options should use the much more natural term "replay"
instead of "rebase".

But then: you said that `--no-rebase-merges` should flatten the commits?
That's not what this option name conveys to me; It would convey to me that
the operation would _abort_ on encountering merge commits.

In other words, I do think that the --linearize option is conceptually
quite distinct from the different modes in which merge commits could be
handled. As such, this option should probably not be conflated with
the various `--replay-merges=<mode>` modes.

> > Now, all these options are (I think) mutually exclusive, so we could
> > consider an option "--replay-merges=<mode>", but personally I find
> > "--<option>=<value>" arguments harder to use than specifying separate
> > options.
> > 
> > I think I'm avoiding your question, because the design of the command
> > line parameters doesn't need tot 1-on-1 correlate to the internal
> > datastructure. And I agree the mode isn't a boolean, but does that mean
> > we want to use an enum internally? Well, I don't know. And I also don't
> > think that matters right now. Code is easy to change, I think the
> > command line options should be designed with the future in mind, which I
> > believe we do with "--linearize".
> > 
> > Sorry for this long-winded rambling, but bottom line I think it's fine
> > to add --linearize and in the future add more options and see how the
> > code should evolve to support those.
> 
> Hm, I dunno. You basically reasoned that we potentially want to have all
> of the same options that git-rebase(1)'s "--rebase-merges=" already
> supports. So that begs the question why we need to reinvent the wheel
> then and not just use the same syntax.

I would strongly caution against repeating the same UX mistakes as `git
rebase` has to live with.

The _functionality_, yes, I think that'd be good to have in `git replay`.
But we can surface that functionality in much better ways, with option
names that reflect the concepts much more intuitively.

Ciao,
Johannes

> Note that I'm not arguing that we should support all of these options
> now. I'm merely arguing that we should try to be consistent, unless
> there is a good argument not to do that. I'm fine with the interface if
> there indeed is a good argument, but if so we should document why we
> think that the current interface in git-rebase(1) is not a good fit for
> this command.
> 
> Thanks!
> 
> Patrick
> 
>