Re: [PATCH v8 3/3] replay: offer an option to linearize the commit topology

Adding my comments in response to Justin's, since I think he
highlights some good points.

First of all, Toon, thanks for making --linearize and multiple
branches incompatible to avoid concatenating histories.  I really
appreciate it.

On Fri, Aug 7, 2026 at 10:34 AM Justin Tobler <[email protected]> wrote:
>
> On 26/07/28 05:45PM, Toon Claes wrote:
> > One of the stated goals of git-replay(1) is to allow implementing the
> > git-rebase(1) functionality on the server side.
> >
> > The default mode of git-rebase(1) is to act as if `--no-rebase-merges`
> > was given. This mode drops merge commits instead of replaying them, and
> > linearizes the history into a sequence of regular (single-parent)
> > commits.
> >
> > Add option `--linearize` to git-replay(1) to do the same. Each replayed
> > commit is stacked on top of the previously replayed one. When a merge is
> > encountered, the commits reachable from all of its sides are replayed
> > into the single line and the merge itself is dropped.
> >
> > If a ref was pointing to a merge commit, that ref is updated to the
> > merge's last replayed ancestor.
>
> Just to clarify, does it really matter if the ref was pointing to the
> merge commit directly? I assume it is just "flattening" the merge
> commits in the revision range.

Toon's clarification is important, though depending on your mental
model it might _appear_ to be an unnecessary clarification.  I think
there are two mental models:
  - Each commit of the branch is replayed and the ref is updated as it
goes.  (This matches underlying implementation mechanics for `git
rebase`, but not for `git replay`.)
  - Each commit of the branch is replayed.  The ref is updated at the
end to the corresponding replay of the final commit.  (Matches
underlying implementation mechanics for `git replay`.)

Readers could possibly assume either mental model without knowing the
underlying mechanics.  Toon's clarification doesn't hurt those who
assume the first style, but is an important clarification for those
who assume the second style.

> > git-replay(1) accepts multiple revision ranges, for example:
> >
> >     $ git replay --onto main topic1 topic2
>
> Per some discussion earlier in the thread, is "accepts multiple revision
> ranges" the correct wording here? Would it be more correct to say
> multiple branches instead?

Yes, please; it would be nice to see this fixed.

> > Without `--linearize` this replays 'topic1' and 'topic2' onto 'main'
> > independently and updates both refs.
>
> Ok, so git-replay(1) updates each branch sepecified separately.

Oh, that's a good callout.  The word "independently" and "separately"
here may well mislead users.  If branches "topic1" and "topic2" share
some history, claiming they are replayed "independently" or
"separately" may cause people to assume the shared history becomes
copied and no longer shared.  I think the word "independently" should
be dropped.  If wanted, we could word this to something like:

Without `--linearize` this replays 'topic1' and 'topic2' onto 'main'
(keeping shared portions of history shared and keeping divergent parts
divergent), and updates both refs.

> > For now this is disallowed with option `--linearize`. Linearizing more
> > than one branch at once would concatenate unrelated histories into a
> > single line, and update each branch to some point in that line. That
> > won't be the result most users want, especially because the order
> > depends on the order of the revision walk, not the order of the branch
> > names on the command line.
>
> I'm not quite sure I follow. Why would the inclusion of the
> `--linearize` option force concatenation of multiple references? Is it
> mot possible to linearize each of the branches in isolation and update
> the reference accordingly?

Maybe:

Due to current implementation limitations, replaying multiple branches
with `--linearize` is disallowed to avoid concatenating unrelated
histories into a single line...

?

> > For the same reason disallow the use of `--contained` with
> > `--linearize`.

Good catch and callout, Toon.

> > Users who want to linearize multiple branches are advised to do this in
> > separate git-replay(1) invocations. Linearizing multiple branches at
> > once might be added later.
>
> Ok.
>
> > Note that `--linearize` is not modeled after git-rebase(1)'s
> > `--rebase-merges[=<mode>]` interface. Recreating merges, by preserving
> > their topology, is a distinct operation that would be a separate mode.
> > `--linearize` only drops merges and replays commits linearly. So
> > git-replay(1) uses its own option rather than reusing that interface.
> >
> > Based-on-patches-by: Johannes Schindelin <[email protected]>
> > Signed-off-by: Toon Claes <[email protected]>
> > ---
> >  Documentation/git-replay.adoc |  19 +++++++-
> >  builtin/replay.c              |   6 ++-
> >  replay.c                      |  60 +++++++++++++++--------
> >  replay.h                      |   5 ++
> >  t/t3650-replay-basics.sh      | 109 +++++++++++++++++++++++++++++++++++++++++-
> >  5 files changed, 176 insertions(+), 23 deletions(-)
> >
> > diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
> > index a32f72aead..656a6924d9 100644
> > --- a/Documentation/git-replay.adoc
> > +++ b/Documentation/git-replay.adoc
> > @@ -10,7 +10,7 @@ SYNOPSIS
> >  --------
> >  [verse]
> >  (EXPERIMENTAL!) 'git replay' ([--contained] --onto=<newbase> | --advance=<branch> | --revert=<branch>)
> > -                          [--ref=<ref>] [--ref-action=<mode>] <revision-range>
> > +                          [--ref=<ref>] [--ref-action=<mode>] [--linearize] <revision-range>
> >
> >  DESCRIPTION
> >  -----------
> > @@ -88,6 +88,23 @@ incompatible with `--contained` (which is a modifier for `--onto` only).
> >  +
> >  The default mode can be configured via the `replay.refAction` configuration variable.
> >
> > +--linearize::
> > +     In this mode, each replayed commit is stacked on top of the
> > +     previously replayed one, so all replayed commits are flattened into
> > +     a single linear history.
> > ++
> > +When a merge commit is encountered, the behavior of git-rebase(1)'s
> > +option `--no-rebase-merges` is imitated. All commits in the range

I dislike pointing new users to read a big chunk of another manual
page to understand an option.  I have a personal gripe against the
manual for `git merge-base`, in particular, which feels like in order
to understand various flags you have to understand what at first looks
like an unrelated command and multiple of its options first.  The rest
of your paragraph is a good self-standing description; can you just
move your first sentence to the end of the paragraph and make it a
parenthetical pointing out the similarity of the two options of the
two commands?

> > +reachable from the merge commit are replayed into a linear history, and
> > +the merge commit itself is dropped. A ref that pointed to a merge commit
> > +is updated to the merge's last replayed ancestor.
> > ++
> > +Only a single branch can be linearized at a time: `--linearize` cannot
> > +be combined with multiple positive revisions or with `--contained`,
> > +because that would concatenate otherwise unrelated histories into one
> > +line. To linearize several branches, replay them in separate `git
> > +replay` invocations.
>
> I still don't fully understand the justification here. I'm not sure it
> really needs to be in the documentation though. It may be fine to just
> say "multiple branches are not supported with this option" or something
> along those lines.

It does feel like this unnecessarily explains implementation
shortcomings, and further tries to list them as fundamental
limitations.  (If each commit were tagged with all branches it was
reachable from, then as the replay walked over the commits and
replayed each, it could simply track the last commit for each branch
rather than an overall last commit, and at the end update each branch
to its corresponding last seen commit.  That would allow us to lift
the limitation.)  So, I agree with Justin's suggestion here to just
more simply state that the combination isn't supported.

> > +
> >  <revision-range>::
> >       Range of commits to replay; see "Specifying Ranges" in
> >       linkgit:git-rev-parse[1]. In `--advance=<branch>` or
> > diff --git a/builtin/replay.c b/builtin/replay.c
> > index 39e3a86f6c..d39626a37d 100644
> > --- a/builtin/replay.c
> > +++ b/builtin/replay.c
> > @@ -85,7 +85,7 @@ int cmd_replay(int argc,
> >       const char *const replay_usage[] = {
> >               N_("(EXPERIMENTAL!) git replay "
> >                  "([--contained] --onto=<newbase> | --advance=<branch> | --revert=<branch>)\n"
> > -                "[--ref=<ref>] [--ref-action=<mode>] <revision-range>"),
> > +                "[--ref=<ref>] [--ref-action=<mode>] [--linearize] <revision-range>"),
> >               NULL
> >       };
> >       struct option replay_options[] = {
> > @@ -111,6 +111,8 @@ int cmd_replay(int argc,
> >                            N_("mode"),
> >                            N_("control ref update behavior (update|print)"),
> >                            PARSE_OPT_NONEG),
> > +             OPT_BOOL(0, "linearize", &opts.linearize,
> > +                      N_("drop merge commits, replaying only non-merge commits")),
> >               OPT_END()
> >       };
> >
> > @@ -132,6 +134,8 @@ int cmd_replay(int argc,
> >                                 opts.contained, "--contained");
> >       die_for_incompatible_opt2(!!opts.ref, "--ref",
> >                                 !!opts.contained, "--contained");
> > +     die_for_incompatible_opt2(opts.linearize, "--linearize",
> > +                               !!opts.contained, "--contained");
> >
> >       /* Parse ref action mode from command line or config */
> >       ref_mode = get_ref_action_mode(repo, ref_action);
> > diff --git a/replay.c b/replay.c
> > index 7e35f40d37..1e1bc7c10a 100644
> > --- a/replay.c
> > +++ b/replay.c
> > @@ -404,6 +404,12 @@ int replay_revisions(struct rev_info *revs,
> >       set_up_replay_mode(revs->repo, &revs->cmdline, opts->onto,
> >                          &detached_head, &advance, &revert, &onto, &update_refs);
> >
> > +     if (opts->linearize &&
> > +         update_refs && strset_get_size(update_refs) > 1) {
> > +             ret = error(_("'--linearize' cannot be used with multiple revision ranges"));
>
> Should this say "multiple branches" instead?

Yes, please.

Also, should we replace opts->linearize with (opts->linearize || mode
== REPLAY_MODE_REVERT) ?  The reason being this line of code below:

> > +                     if (opts->linearize || mode == REPLAY_MODE_REVERT)
> > +                             base = last_commit;

Trying to revert with multiple branches will (a) concatenate the
reverts into a single branch (which probably *is* what is wanted) and
(b) do so in revision walking order instead of the order of branches
specified by the user on the command line.  That ordering could have
bisection or conflict ramifications that may surprise the user.  Also,
cherry-pick disallows multiple branches (even though concatenation
would be wanted there too) because of this
ignore-user's-command-line-order issue.