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

[Justin Tobler <jltobler@gmail.com>]

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.

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

> Without `--linearize` this replays 'topic1' and 'topic2' onto 'main'
> independently and updates both refs.

Ok, so git-replay(1) updates each branch sepecified separately.

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

> For the same reason disallow the use of `--contained` with
> `--linearize`.
> 
> 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 <johannes.schindelin@gmx.de>
> Signed-off-by: Toon Claes <toon@iotcl.com>
> ---
>  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
> +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.

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

> +		goto out;
> +	}
> +
>  	if (opts->ref) {
>  		struct object_id oid;
>  
> @@ -437,26 +443,40 @@ int replay_revisions(struct rev_info *revs,
>  	while ((commit = get_revision(revs))) {
>  		const struct name_decoration *decoration;
>  
> -		/*
> -		 * Decide where to replay this commit on.
> -		 * If the parent commit was replayed already, the replayed result
> -		 * can be found in `replayed_commits`. Otherwise fall back to `onto`.
> -		 * When reverting, commits are replayed in reverse order and thus
> -		 * its parent isn't replayed yet. Therefore revert commits are
> -		 * always replayed onto `last_commit`.
> -		 */
> -		struct commit *parent = commit->parents ? commit->parents->item : NULL;
> -		struct commit *base = get_mapped_commit(replayed_commits, parent, onto);
> -
> -		if (mode == REPLAY_MODE_REVERT)
> -			base = last_commit;
> -
> -		if (commit->parents && commit->parents->next)
> -			die(_("replaying merge commits is not supported yet!"));
> -
> -		last_commit = pick_regular_commit(revs->repo, commit, base,
> -						  &merge_opt, &result,
> -						  mode, opts->empty);
> +		if (commit->parents && commit->parents->next) {
> +			if (!opts->linearize)
> +				die(_("replaying merge commits is not supported yet!"));
> +			/*
> +			 * Drop the merge commit: do not pick it, leave
> +			 * `last_commit` unchanged, and fall through to the
> +			 * rest of the loop. As a result:
> +			 * - refs pointing to the merge commit will be updated
> +			 *   to `last_commit`.
> +			 * - the next replayed commit uses `last_commit` as its
> +			 *   `base`.
> +			 */

Ok, when the linearize option is provided, we now drop the merge commit
and continue on.

> +		} else {
> +			/*
> +			 * Decide where to replay this commit onto.
> +			 * If the parent commit was replayed already, the replayed result
> +			 * can be found in `replayed_commits`. Otherwise fall back to `onto`.
> +			 * When reverting, commits are replayed in reverse order and thus
> +			 * its parent isn't replayed yet. Therefore revert commits are
> +			 * always replayed onto `last_commit`.
> +			 * Also when opts->linearize is true, set the base to
> +			 * `last_commit` to create a single linear history.
> +			 */
> +			struct commit *parent = commit->parents ? commit->parents->item : NULL;
> +			struct commit *base = get_mapped_commit(replayed_commits, parent, onto);
> +
> +			if (opts->linearize || mode == REPLAY_MODE_REVERT)
> +				base = last_commit;

Ok IIUC, when we are linearizing commits we are just replaying them onto
the most recently replayed commit. Makes sense.

-Justin