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

[Junio C Hamano <gitster@pobox.com>]

Toon Claes <toon@iotcl.com> writes:

> From: Johannes Schindelin <Johannes.Schindelin@gmx.de>
> ...
> Linearizing is a distinct operation, and flattening merge commits is
> just one aspect of that. Recreating merges would be a separate mode, so
> rather than mirror git-rebase(1)'s `--rebase-merges[=<mode>]` interface,
> git-replay(1) uses its own `--linearize` option.
>
> Co-authored-by: Toon Claes <toon@iotcl.com>
> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
> Signed-off-by: Toon Claes <toon@iotcl.com>
> ---
>  Documentation/git-replay.adoc |  21 ++++++-
>  builtin/replay.c              |   6 +-
>  replay.c                      |  54 ++++++++++------
>  replay.h                      |   5 ++
>  t/t3650-replay-basics.sh      | 140 +++++++++++++++++++++++++++++++++++++++++-
>  5 files changed, 203 insertions(+), 23 deletions(-)

With such an extensive change in behaviour, I wonder if Dscho is
still responsible for latent bugs in this round of implementation
and documentation, or should you take the responsibility over?

> +--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
> +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.
> ++
> +This flattens the `<revision-range>` as a whole. When multiple revision
> +ranges are given they are stacked on top of each other into one linear
> +history. Each of their refs is updated to point to its position in that
> +history. To linearize ranges separately, replay them in separate `git
> +replay` invocations.

OK, very much understandable.

> +This option is incompatible with `--revert`.

Definitely it is OK to leave it outside the scope, but I am not sure
if reverting a group of commits that happens to be "closed" and
happens to contain merges, is inherently incompatible with
flattening.  If you have

    ----O--A
         \  \
          B--M--C

and you want to revert what happened while the history advanced from
O to M, I would naïvely expect that I can arrive at

    ----O--A
         \  \
          B--M--C-B'-A'

by linearly applying the inverse of A and B (in either order).

If it is an inherent limitation, then the sentence may want "because
..." at the end.  Otherwise, it would make more sense to strike the
sentence from the main text, and have BUGS (or LIMITATIONS) section
at the end of the page, perhaps?