{"thread":{"id":"64549","subject":"[PATCH] Documentation/git-replay.adoc: fix errors around revision range","startedAt":"2025-11-29T04:44:28Z","lastAt":"2025-11-29T14:59:25Z","messageCount":2,"participants":["Elijah Newren via GitGitGadget","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"531423","messageId":"pull.2012.git.1764391464952.gitgitgadget@gmail.com","threadId":"64549","inReplyTo":null,"subject":"[PATCH] Documentation/git-replay.adoc: fix errors around revision range","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-11-29T04:44:24Z","receivedAt":"2025-11-29T04:44:28Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nThere was significant confusion in the git-replay manual about what\nconstitutes a revision range. As noted in f302c1e4aa09 (revisions(7):\nclarify that most commands take a single revision range, 2021-05-18):\n\n Commands that are specifically designed to take two distinct ranges\n (e.g. \"git range-diff R1 R2\" to compare two ranges) do exist, but they\n are exceptions. Unless otherwise noted, all \"git\" commands that operate\n on a set of commits work on a single revision range.\n\n`git replay` is not an exception, but a few places in the manual were\nwritten as though it were. These appear to have come in revisions to\nthe original series, between v3->v4 (see\nhttps://lore.kernel.org/git/CAP8UFD3bpLrVW97DH7j=V9H2GsTSAkksC9L3QujQERFk_kLnZA@mail.gmail.com/\n, \"More than one can be passed\") and between v6->v7\n(https://lore.kernel.org/git/20231115143327.2441397-1-christian.couder@gmail.com/,\n\"Takes ranges of commits\"), and I missed both of these revisions when\nreviewing. Fix them now.\n\nThere was also a reference to the \"Commit Limiting options below\", but\nthis page has no such section of options; strike the misleading\nreference.\n\nIt is worth noting that we are documenting existing behavior, rather\nthan optimal behavior. Junio has multiple times suggested introducing\nalternative ways to walk revisions and use them in `git replay\n--advance`, e.g. at\n * https://lore.kernel.org/git/xmqqy1mqo6kv.fsf@gitster.g/\n * https://lore.kernel.org/git/xmqq8rb3is8c.fsf@gitster.g/\n * https://lore.kernel.org/git/xmqqtsydj2zk.fsf@gitster.g/ (item (2))\nIf/when we introduce some new revision walking flag that implements one\nof these alternate types of revision walks, we can update the --advance\noption and this manual appropriately.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-replay.adoc: fix errors around revision range\n \n This has a minor conflict with Phillip's recent patch where he adds an\n extra sentence to the description for , to note that\n empty commits will be dropped. (See\n https://lore.kernel.org/git/8a2a1215306452147cc7b803530ab2429bf57f15.1764260150.git.phillip.wood@dunelm.org.uk/)\n The resolution is simply appending that sentence from his patch to the\n rewritten description from this patch. If you prefer I wait and resend\n after Phillip's patch merges (which in turn will wait until after\n ps/history), just let me know.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2012%2Fnewren%2Freplay-revision-range-wording-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2012/newren/replay-revision-range-wording-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2012\n\n Documentation/git-replay.adoc | 13 ++++++-------\n builtin/replay.c | 2 +-\n 2 files changed, 7 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex dcb26e8a8e..d03235cca0 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -9,12 +9,12 @@ git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos t\n SYNOPSIS\n --------\n [verse]\n-(EXPERIMENTAL!) 'git replay' ([--contained] --onto | --advance ) [--ref-action[=]] ...\n+(EXPERIMENTAL!) 'git replay' ([--contained] --onto | --advance ) [--ref-action[=]] \n \n DESCRIPTION\n -----------\n \n-Takes ranges of commits and replays them onto a new location. Leaves\n+Takes a range of commits and replays them onto a new location. Leaves\n the working tree and the index untouched. By default, updates the\n relevant references using an atomic transaction (all refs update or\n none). Use `--ref-action=print` to avoid automatic ref updates and\n@@ -55,11 +55,10 @@ which uses the target only as a starting point without updating it.\n The default mode can be configured via the `replay.refAction` configuration variable.\n \n ::\n-\tRange of commits to replay. More than one can\n-\tbe passed, but in `--advance ` mode, they should have\n-\ta single tip, so that it's clear where should point\n-\tto. See \"Specifying Ranges\" in linkgit:git-rev-parse[1] and the\n-\t\"Commit Limiting\" options below.\n+\tRange of commits to replay; see \"Specifying Ranges\" in\n+\tlinkgit:git-rev-parse[1]. In `--advance ` mode, the\n+\trange should have a single tip, so that it's clear to which tip the\n+\tadvanced should point.\n \n include::rev-list-options.adoc[]\n \ndiff --git a/builtin/replay.c b/builtin/replay.c\nindex 6606a2c94b..e6d6d28239 100644\n--- a/builtin/replay.c\n+++ b/builtin/replay.c\n@@ -366,7 +366,7 @@ int cmd_replay(int argc,\n \tconst char *const replay_usage[] = {\n \t\tN_(\"(EXPERIMENTAL!) git replay \"\n \t\t \"([--contained] --onto | --advance ) \"\n-\t\t \"[--ref-action[=]] ...\"),\n+\t\t \"[--ref-action[=]] \"),\n \t\tNULL\n \t};\n \tstruct option replay_options[] = {\n\nbase-commit: b31ab939fe8e3cbe8be48dddd1c6ac0265991f45\n-- \ngitgitgadget\n"},{"id":"531431","messageId":"xmqqcy50hol1.fsf@gitster.g","threadId":"64549","inReplyTo":"pull.2012.git.1764391464952.gitgitgadget@gmail.com","subject":"Re: [PATCH] Documentation/git-replay.adoc: fix errors around revision range","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-11-29T14:59:22Z","receivedAt":"2025-11-29T14:59:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Elijah Newren via GitGitGadget\" writes:\n\n> From: Elijah Newren \n>\n> There was significant confusion in the git-replay manual about what\n> constitutes a revision range. As noted in f302c1e4aa09 (revisions(7):\n> clarify that most commands take a single revision range, 2021-05-18):\n>\n> Commands that are specifically designed to take two distinct ranges\n> (e.g. \"git range-diff R1 R2\" to compare two ranges) do exist, but they\n> are exceptions. Unless otherwise noted, all \"git\" commands that operate\n> on a set of commits work on a single revision range.\n>\n> `git replay` is not an exception, but a few places in the manual were\n> written as though it were. These appear to have come in revisions to\n> the original series, between v3->v4 (see\n> https://lore.kernel.org/git/CAP8UFD3bpLrVW97DH7j=V9H2GsTSAkksC9L3QujQERFk_kLnZA@mail.gmail.com/\n> , \"More than one can be passed\") and between v6->v7\n> (https://lore.kernel.org/git/20231115143327.2441397-1-christian.couder@gmail.com/,\n> \"Takes ranges of commits\"), and I missed both of these revisions when\n> reviewing. Fix them now.\n>\n> There was also a reference to the \"Commit Limiting options below\", but\n> this page has no such section of options; strike the misleading\n> reference.\n>\n> It is worth noting that we are documenting existing behavior, rather\n> than optimal behavior. Junio has multiple times suggested introducing\n> alternative ways to walk revisions and use them in `git replay\n> --advance`, e.g. at\n> * https://lore.kernel.org/git/xmqqy1mqo6kv.fsf@gitster.g/\n> * https://lore.kernel.org/git/xmqq8rb3is8c.fsf@gitster.g/\n> * https://lore.kernel.org/git/xmqqtsydj2zk.fsf@gitster.g/ (item (2))\n> If/when we introduce some new revision walking flag that implements one\n> of these alternate types of revision walks, we can update the --advance\n> option and this manual appropriately.\n>\n> Signed-off-by: Elijah Newren \n> ---\n> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n> index dcb26e8a8e..d03235cca0 100644\n> --- a/Documentation/git-replay.adoc\n> +++ b/Documentation/git-replay.adoc\n> @@ -9,12 +9,12 @@ git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos t\n> SYNOPSIS\n> --------\n> [verse]\n> -(EXPERIMENTAL!) 'git replay' ([--contained] --onto | --advance ) [--ref-action[=]] ...\n> +(EXPERIMENTAL!) 'git replay' ([--contained] --onto | --advance ) [--ref-action[=]] \n\nGlad to see this overly long line shrink by a few characters, but we\nneed to shrink more or line wrap to bring it below the acceptable\nwidth like 65-75 characters. That is obviously not the reason why\nwe are losing \"...\" here, and outside the scope of this patch ;-).\n\n> -Takes ranges of commits and replays them onto a new location. Leaves\n> +Takes a range of commits and replays them onto a new location. Leaves\n\nOK.\n\n> @@ -55,11 +55,10 @@ which uses the target only as a starting point without updating it.\n> The default mode can be configured via the `replay.refAction` configuration variable.\n> \n> ::\n> +\tRange of commits to replay; see \"Specifying Ranges\" in\n> +\tlinkgit:git-rev-parse[1]. In `--advance ` mode, the\n> +\trange should have a single tip, so that it's clear to which tip the\n> +\tadvanced should point.\n\nGood.\n\n> diff --git a/builtin/replay.c b/builtin/replay.c\n> index 6606a2c94b..e6d6d28239 100644\n> --- a/builtin/replay.c\n> +++ b/builtin/replay.c\n> @@ -366,7 +366,7 @@ int cmd_replay(int argc,\n> \tconst char *const replay_usage[] = {\n> \t\tN_(\"(EXPERIMENTAL!) git replay \"\n> \t\t \"([--contained] --onto | --advance ) \"\n> -\t\t \"[--ref-action[=]] ...\"),\n> +\t\t \"[--ref-action[=]] \"),\n> \t\tNULL\n> \t};\n> \tstruct option replay_options[] = {\n>\n> base-commit: b31ab939fe8e3cbe8be48dddd1c6ac0265991f45\n\nThanks, will apply.\n"}]}