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

[newren]

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.

cc: Phillip Wood [email protected]
cc: Christian Couder [email protected]

[newren]

/submit

[gitgitgadget]

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2012/newren/replay-revision-range-wording-v1

To fetch this version to local tag pr-2012/newren/replay-revision-range-wording-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2012/newren/replay-revision-range-wording-v1

[gitgitgadget]

This patch series was integrated into seen via git@831985c.

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Elijah Newren via GitGitGadget" <[email protected]> writes:

> From: Elijah Newren <[email protected]>
>
> 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/[email protected]/,
> "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/[email protected]/
>   * https://lore.kernel.org/git/[email protected]/
>   * https://lore.kernel.org/git/[email protected]/ (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 <[email protected]>
> ---
> 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.

[gitgitgadget]

This branch is now known as en/replay-doc-revision-range.

[gitgitgadget]

This patch series was integrated into seen via git@e4c05c5.

[gitgitgadget]

This patch series was integrated into next via git@37ba09b.

[gitgitgadget]

There was a status update in the "New Topics" section about the branch en/replay-doc-revision-range on the Git mailing list:

The use of "revision" (a connected set of commits) has been
clarified in the "git replay" documentation.

Will merge to 'master'.
source: <[email protected]>