From: Junio C Hamano Date: Sat, 29 Nov 2025 14:59:22 GMT Subject: Re: [PATCH] Documentation/git-replay.adoc: fix errors around revision range Message-ID: In-Reply-To: "Elijah Newren via GitGitGadget" writes: > From: Elijah Newren > > 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 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 > --- > 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 | --advance ) [--ref-action[=]] ... > +(EXPERIMENTAL!) 'git replay' ([--contained] --onto | --advance ) [--ref-action[=]] 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. > > :: > + Range of commits to replay; see "Specifying Ranges" in > + linkgit:git-rev-parse[1]. In `--advance ` mode, the > + range should have a single tip, so that it's clear to which tip the > + advanced 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 | --advance ) " > - "[--ref-action[=]] ..."), > + "[--ref-action[=]] "), > NULL > }; > struct option replay_options[] = { > > base-commit: b31ab939fe8e3cbe8be48dddd1c6ac0265991f45 Thanks, will apply.