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

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Elijah Newren committed Nov 29, 2025 at 04:44 UTC 136f86abc052ef6186d9985fc26833ffc0484888
2 files changed +7 -8
Documentation/git-replay.adoc
+6 -7
@@ -9,12 +9,12 @@ git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos t
9 SYNOPSIS
10 --------
11 [verse]
12 -(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) [--ref-action[=<mode>]] <revision-range>...
12 +(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) [--ref-action[=<mode>]] <revision-range>
13
14 DESCRIPTION
15 -----------
16
17 -Takes ranges of commits and replays them onto a new location. Leaves
17 +Takes a range of commits and replays them onto a new location. Leaves
18 the working tree and the index untouched. By default, updates the
19 relevant references using an atomic transaction (all refs update or
20 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.
55 The default mode can be configured via the `replay.refAction` configuration variable.
56
57 <revision-range>::
58 - Range of commits to replay. More than one <revision-range> can
59 - be passed, but in `--advance <branch>` mode, they should have
60 - a single tip, so that it's clear where <branch> should point
61 - to. See "Specifying Ranges" in linkgit:git-rev-parse[1] and the
62 - "Commit Limiting" options below.
58 + Range of commits to replay; see "Specifying Ranges" in
59 + linkgit:git-rev-parse[1]. In `--advance <branch>` mode, the
60 + range should have a single tip, so that it's clear to which tip the
61 + advanced <branch> should point.
62
63 include::rev-list-options.adoc[]
64
builtin/replay.c
+1 -1
@@ -366,7 +366,7 @@ int cmd_replay(int argc,
366 const char *const replay_usage[] = {
367 N_("(EXPERIMENTAL!) git replay "
368 "([--contained] --onto <newbase> | --advance <branch>) "
369 - "[--ref-action[=<mode>]] <revision-range>..."),
369 + "[--ref-action[=<mode>]] <revision-range>"),
370 NULL
371 };
372 struct option replay_options[] = {