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

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

[Elijah Newren via GitGitGadget]

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>
---
    Documentation/git-replay.adoc: fix errors around revision range
    
    This has a minor conflict with Phillip's recent patch where he adds an
    extra sentence to the description for <revision range>, to note that
    empty commits will be dropped. (See
    https://lore.kernel.org/git/8a2a1215306452147cc7b803530ab2429bf57f15.1764260150.git.phillip.wood@dunelm.org.uk/)
    The resolution is simply appending that sentence from his patch to the
    rewritten description from this patch. If you prefer I wait and resend
    after Phillip's patch merges (which in turn will wait until after
    ps/history), just let me know.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2012%2Fnewren%2Freplay-revision-range-wording-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2012/newren/replay-revision-range-wording-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2012

 Documentation/git-replay.adoc | 13 ++++++-------
 builtin/replay.c              |  2 +-
 2 files changed, 7 insertions(+), 8 deletions(-)

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>
 
 DESCRIPTION
 -----------
 
-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
 the working tree and the index untouched. By default, updates the
 relevant references using an atomic transaction (all refs update or
 none). Use `--ref-action=print` to avoid automatic ref updates and
@@ -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. More than one <revision-range> can
-	be passed, but in `--advance <branch>` mode, they should have
-	a single tip, so that it's clear where <branch> should point
-	to. See "Specifying Ranges" in linkgit:git-rev-parse[1] and the
-	"Commit Limiting" options below.
+	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.
 
 include::rev-list-options.adoc[]
 
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
-- 
gitgitgadget

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

[Junio C Hamano]

"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.