Re: [PATCH] Documentation/git-replay.adoc: fix errors around revision range

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

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Elijah Newren <newren@gmail.com>
>
> There was significant confusion in the git-replay manual about what
> constitutes a revision range.  As noted in f302c1e4aa09 (revisions(7):
> clarify that most commands take a single revision range, 2021-05-18):
>
>    Commands that are specifically designed to take two distinct ranges
>    (e.g. "git range-diff R1 R2" to compare two ranges) do exist, but they
>    are exceptions. Unless otherwise noted, all "git" commands that operate
>    on a set of commits work on a single revision range.
>
> `git replay` is not an exception, but a few places in the manual were
> written as though it were.  These appear to have come in revisions to
> the original series, between v3->v4 (see
> https://lore.kernel.org/git/CAP8UFD3bpLrVW97DH7j=V9H2GsTSAkksC9L3QujQERFk_kLnZA@mail.gmail.com/
> , "More than one <revision-range> can be passed") and between v6->v7
> (https://lore.kernel.org/git/20231115143327.2441397-1-christian.couder@gmail.com/,
> "Takes ranges of commits"), and I missed both of these revisions when
> reviewing.  Fix them now.
>
> There was also a reference to the "Commit Limiting options below", but
> this page has no such section of options; strike the misleading
> reference.
>
> It is worth noting that we are documenting existing behavior, rather
> than optimal behavior.  Junio has multiple times suggested introducing
> alternative ways to walk revisions and use them in `git replay
> --advance`, e.g. at
>   * https://lore.kernel.org/git/xmqqy1mqo6kv.fsf@gitster.g/
>   * https://lore.kernel.org/git/xmqq8rb3is8c.fsf@gitster.g/
>   * https://lore.kernel.org/git/xmqqtsydj2zk.fsf@gitster.g/ (item (2))
> If/when we introduce some new revision walking flag that implements one
> of these alternate types of revision walks, we can update the --advance
> option and this manual appropriately.
>
> Signed-off-by: Elijah Newren <newren@gmail.com>
> ---
> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
> index dcb26e8a8e..d03235cca0 100644
> --- a/Documentation/git-replay.adoc
> +++ b/Documentation/git-replay.adoc
> @@ -9,12 +9,12 @@ git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos t
>  SYNOPSIS
>  --------
>  [verse]
> -(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) [--ref-action[=<mode>]] <revision-range>...
> +(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) [--ref-action[=<mode>]] <revision-range>

Glad to see this overly long line shrink by a few characters, but we
need to shrink more or line wrap to bring it below the acceptable
width like 65-75 characters.  That is obviously not the reason why
we are losing "..." here, and outside the scope of this patch ;-).

> -Takes ranges of commits and replays them onto a new location. Leaves
> +Takes a range of commits and replays them onto a new location. Leaves

OK.

> @@ -55,11 +55,10 @@ which uses the target only as a starting point without updating it.
>  The default mode can be configured via the `replay.refAction` configuration variable.
>  
>  <revision-range>::
> +	Range of commits to replay; see "Specifying Ranges" in
> +	linkgit:git-rev-parse[1]. In `--advance <branch>` mode, the
> +	range should have a single tip, so that it's clear to which tip the
> +	advanced <branch> should point.

Good.

> diff --git a/builtin/replay.c b/builtin/replay.c
> index 6606a2c94b..e6d6d28239 100644
> --- a/builtin/replay.c
> +++ b/builtin/replay.c
> @@ -366,7 +366,7 @@ int cmd_replay(int argc,
>  	const char *const replay_usage[] = {
>  		N_("(EXPERIMENTAL!) git replay "
>  		   "([--contained] --onto <newbase> | --advance <branch>) "
> -		   "[--ref-action[=<mode>]] <revision-range>..."),
> +		   "[--ref-action[=<mode>]] <revision-range>"),
>  		NULL
>  	};
>  	struct option replay_options[] = {
>
> base-commit: b31ab939fe8e3cbe8be48dddd1c6ac0265991f45

Thanks, will apply.