{"thread":{"id":"65670","subject":"[PATCH 0/4] doc: replay: fix config link","startedAt":"2026-05-21T18:02:14Z","lastAt":"2026-07-31T15:45:48Z","messageCount":40,"participants":["kristofferhaugsbakk@fastmail.com","Junio C Hamano","Kristoffer Haugsbakk","Patrick Steinhardt","Toon Claes"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"543847","messageId":"CV_doc_replay_config.709@msgid.xyz","threadId":"65670","inReplyTo":null,"subject":"[PATCH 0/4] doc: replay: fix config link","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-05-21T18:01:57Z","receivedAt":"2026-05-21T18:02:14Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name: kh/doc-replay-config\n\nTopic summary: link to the config for git-replay(1) (one variable) in\ngit-replay(1) and git-config(1). Also improve the doc for that config\nvariable and `--ref-action`.\n\n[1/4] doc: link to config for git-replay(1)\n[2/4] doc: replay: simplify replay.refAction description\n[3/4] doc: replay: use a nested definition list\n[4/4] doc: replay: move “default” to the right-hand-side\n\n Documentation/config.adoc | 2 ++\n Documentation/config/replay.adoc | 17 +++++++----------\n Documentation/git-replay.adoc | 13 +++++++++----\n 3 files changed, 18 insertions(+), 14 deletions(-)\n\n\nbase-commit: a89346e34a937f001e5d397ee62224e3e9852040\n-- \n2.54.0.13.g9c7419e39f8\n\n"},{"id":"543848","messageId":"doc_replay_link_config.70a@msgid.xyz","threadId":"65670","inReplyTo":"CV_doc_replay_config.709@msgid.xyz","subject":"[PATCH 1/4] doc: link to config for git-replay(1)","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-05-21T18:01:58Z","receivedAt":"2026-05-21T18:02:32Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis config doc was added in 336ac90c (replay: add replay.refAction\nconfig option, 2025-11-06) but never included anywhere. Include it in\ngit-replay(1) and git-config(1).\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/config.adoc | 2 ++\n Documentation/git-replay.adoc | 4 ++++\n 2 files changed, 6 insertions(+)\n\ndiff --git a/Documentation/config.adoc b/Documentation/config.adoc\nindex 62eebe7c545..51fabecb9b0 100644\n--- a/Documentation/config.adoc\n+++ b/Documentation/config.adoc\n@@ -511,6 +511,8 @@ include::config/remotes.adoc[]\n \n include::config/repack.adoc[]\n \n+include::config/replay.adoc[]\n+\n include::config/rerere.adoc[]\n \n include::config/revert.adoc[]\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex a32f72aead3..f9ca2db2833 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -209,6 +209,10 @@ This replays the range `aabbcc..ddeeff` onto commit `112233` and updates\n `refs/heads/mybranch` to point at the result. This can be useful when you want\n to use bare commit IDs instead of branch names.\n \n+CONFIGURATION\n+-------------\n+include::config/replay.adoc[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \n2.54.0.13.g9c7419e39f8\n\n"},{"id":"543849","messageId":"simplify_replay.refAction.70b@msgid.xyz","threadId":"65670","inReplyTo":"CV_doc_replay_config.709@msgid.xyz","subject":"[PATCH 2/4] doc: replay: simplify replay.refAction description","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-05-21T18:01:59Z","receivedAt":"2026-05-21T18:02:51Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nWe don’t need to list what each argument does since the documentation\nfor `--ref-action` does that. So let’s simplify the `replay.refAction`\ndescription by referring to git-replay(1).\n\nAlso make sure to not self-link for the git-replay(1) inclusion.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/config/replay.adoc | 17 +++++++----------\n Documentation/git-replay.adoc | 1 +\n 2 files changed, 8 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\nindex 7d549d2f0e5..42e521694d1 100644\n--- a/Documentation/config/replay.adoc\n+++ b/Documentation/config/replay.adoc\n@@ -1,11 +1,8 @@\n replay.refAction::\n-\tSpecifies the default mode for handling reference updates in\n-\t`git replay`. The value can be:\n-+\n---\n-\t* `update`: Update refs directly using an atomic transaction (default behavior).\n-\t* `print`: Output update-ref commands for pipeline use.\n---\n-+\n-This setting can be overridden with the `--ref-action` command-line option.\n-When not configured, `git replay` defaults to `update` mode.\n+\tSpecifies the default mode for handling reference updates. Either `update` or `print`.\n+ifdef::git-replay[]\n+See `--ref-action`.\n+endif::git-replay[]\n+ifndef::git-replay[]\n+See `--ref-action` for linkgit:git-replay[1] for details.\n+endif::git-replay[]\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex f9ca2db2833..4de85088d6c 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n \n CONFIGURATION\n -------------\n+:git-replay: 1\n include::config/replay.adoc[]\n \n GIT\n-- \n2.54.0.13.g9c7419e39f8\n\n"},{"id":"543850","messageId":"--ref-action_definition_list.70c@msgid.xyz","threadId":"65670","inReplyTo":"CV_doc_replay_config.709@msgid.xyz","subject":"[PATCH 3/4] doc: replay: use a nested definition list","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-05-21T18:02:00Z","receivedAt":"2026-05-21T18:03:09Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis bullet list for `--ref-action` introduces a term with a colon.\nThis is exactly what a definition list is, structurally. Let’s be\nsylistically consistent and use the definition list markup construct.\n\nWe can reuse the `::` delimiter since we use an open block.\nBut for consistency use the typical nested definition list\ndelimiter, namely `;;`.\n\nAlso drop the harmless but unneeded indentation.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-replay.adoc | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 4de85088d6c..b4fe43ec687 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -80,10 +80,10 @@ incompatible with `--contained` (which is a modifier for `--onto` only).\n \tControl how references are updated. The mode can be:\n +\n --\n-\t* `update` (default): Update refs directly using an atomic transaction.\n-\t All refs are updated or none are (all-or-nothing behavior).\n-\t* `print`: Output update-ref commands for pipeline use. This is the\n-\t traditional behavior where output can be piped to `git update-ref --stdin`.\n+`update` (default);; Update refs directly using an atomic transaction.\n+\tAll refs are updated or none are (all-or-nothing behavior).\n+`print`;; Output update-ref commands for pipeline use. This is the\n+\ttraditional behavior where output can be piped to `git update-ref --stdin`.\n --\n +\n The default mode can be configured via the `replay.refAction` configuration variable.\n-- \n2.54.0.13.g9c7419e39f8\n\n"},{"id":"543851","messageId":"default_RHS.70d@msgid.xyz","threadId":"65670","inReplyTo":"CV_doc_replay_config.709@msgid.xyz","subject":"[PATCH 4/4] doc: replay: move “default” to the right-hand-side","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-05-21T18:02:01Z","receivedAt":"2026-05-21T18:03:28Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis is now a definition list (see previous commit) and parentheticals\nlike this do not go on the left-hand-side. Moving it to the other side\nmakes it stand out just as much and is also more consistent with the\nrest of the documentation.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n > do not go on the left-hand-side.\n \n At least I haven’t seen it.\n\n Documentation/git-replay.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex b4fe43ec687..39ecc2e1876 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -80,7 +80,7 @@ incompatible with `--contained` (which is a modifier for `--onto` only).\n \tControl how references are updated. The mode can be:\n +\n --\n-`update` (default);; Update refs directly using an atomic transaction.\n+`update`;; (default) Update refs directly using an atomic transaction.\n \tAll refs are updated or none are (all-or-nothing behavior).\n `print`;; Output update-ref commands for pipeline use. This is the\n \ttraditional behavior where output can be piped to `git update-ref --stdin`.\n-- \n2.54.0.13.g9c7419e39f8\n\n"},{"id":"544305","messageId":"xmqq1pesh783.fsf@gitster.g","threadId":"65670","inReplyTo":"CV_doc_replay_config.709@msgid.xyz","subject":"Re: [PATCH 0/4] doc: replay: fix config link","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-30T22:18:20Z","receivedAt":"2026-05-30T22:18:23Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> [1/4] doc: link to config for git-replay(1)\n> [2/4] doc: replay: simplify replay.refAction description\n> [3/4] doc: replay: use a nested definition list\n> [4/4] doc: replay: move “default” to the right-hand-side\n\nIt is always nice to see documentation gaps filled.\n"},{"id":"544306","messageId":"xmqqse78fsn2.fsf@gitster.g","threadId":"65670","inReplyTo":"doc_replay_link_config.70a@msgid.xyz","subject":"Re: [PATCH 1/4] doc: link to config for git-replay(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-30T22:18:41Z","receivedAt":"2026-05-30T22:18:43Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> This config doc was added in 336ac90c (replay: add replay.refAction\n> config option, 2025-11-06) but never included anywhere. Include it in\n> git-replay(1) and git-config(1).\n>\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n> Documentation/config.adoc | 2 ++\n> Documentation/git-replay.adoc | 4 ++++\n> 2 files changed, 6 insertions(+)\n\nIt is always nice to see documentation gaps filled.\n\nThe `replay.refAction` configuration variable was indeed left\ndangling without a proper link from the main command documentation,\nwhich is embarrassing. I wonder if we can add simple \"doc-lint\"\nrule or two to prevent similar mistakes from happening again?\n\n> diff --git a/Documentation/config.adoc b/Documentation/config.adoc\n> index 62eebe7c545..51fabecb9b0 100644\n> --- a/Documentation/config.adoc\n> +++ b/Documentation/config.adoc\n> @@ -511,6 +511,8 @@ include::config/remotes.adoc[]\n> \n> include::config/repack.adoc[]\n> \n> +include::config/replay.adoc[]\n> +\n> include::config/rerere.adoc[]\n> \n> include::config/revert.adoc[]\n\nPlacing `include::config/replay.adoc[]` in `config.adoc`\nalphabetically between `repack` and `rerere` is correct, as the list\nis alphabetical.\n\n> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n> index a32f72aead3..f9ca2db2833 100644\n> --- a/Documentation/git-replay.adoc\n> +++ b/Documentation/git-replay.adoc\n> @@ -209,6 +209,10 @@ This replays the range `aabbcc..ddeeff` onto commit `112233` and updates\n> `refs/heads/mybranch` to point at the result. This can be useful when you want\n> to use bare commit IDs instead of branch names.\n> \n> +CONFIGURATION\n> +-------------\n> +include::config/replay.adoc[]\n> +\n\nAdding the `CONFIGURATION` section near the end of `git-replay.adoc`\nis also the standard way we expose configuration variables to the\ncommand's manual page.\n\nLooking good.\n\n> GIT\n> ---\n> Part of the linkgit:git[1] suite\n"},{"id":"544307","messageId":"xmqq33z8fs5r.fsf@gitster.g","threadId":"65670","inReplyTo":"simplify_replay.refAction.70b@msgid.xyz","subject":"Re: [PATCH 2/4] doc: replay: simplify replay.refAction description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-30T22:29:04Z","receivedAt":"2026-05-30T22:29:07Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> replay.refAction::\n> -\tSpecifies the default mode for handling reference updates in\n> -\t`git replay`. The value can be:\n> -+\n> ---\n> -\t* `update`: Update refs directly using an atomic transaction (default behavior).\n> -\t* `print`: Output update-ref commands for pipeline use.\n> ---\n> -+\n> -This setting can be overridden with the `--ref-action` command-line option.\n> -When not configured, `git replay` defaults to `update` mode.\n> +\tSpecifies the default mode for handling reference updates. Either `update` or `print`.\n> +ifdef::git-replay[]\n> +See `--ref-action`.\n> +endif::git-replay[]\n> +ifndef::git-replay[]\n> +See `--ref-action` for linkgit:git-replay[1] for details.\n> +endif::git-replay[]\n\nThis makes it a bit roundabout for \"git config --help\" readers who\nwanted to figure out what value to set to the configuration\nvariable, because the valid choices are no longer listed here.\n\nFinding `--ref-action=` and its description in the other page\nis straight-forward, so it may not be too bad, though.\n\n> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n> index f9ca2db2833..4de85088d6c 100644\n> --- a/Documentation/git-replay.adoc\n> +++ b/Documentation/git-replay.adoc\n> @@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n> \n> CONFIGURATION\n> -------------\n> +:git-replay: 1\n> include::config/replay.adoc[]\n\nThe use of conditional attributes (`ifdef::git-replay[]`) is a neat\nand standard way to tailor the description depending on whether it\nis read as part of `git-config(1)` or `git-replay(1)`. It correctly\npoints the reader to `--ref-action` in the latter case, and provides\na full `linkgit` reference in the former. Clean and correct.\n"},{"id":"544308","messageId":"xmqqy0h0ed7h.fsf@gitster.g","threadId":"65670","inReplyTo":"simplify_replay.refAction.70b@msgid.xyz","subject":"Re: [PATCH 2/4] doc: replay: simplify replay.refAction description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-30T22:37:22Z","receivedAt":"2026-05-30T22:37:25Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> replay.refAction::\n> -\tSpecifies the default mode for handling reference updates in\n> -\t`git replay`. The value can be:\n> -+\n> ---\n> -\t* `update`: Update refs directly using an atomic transaction (default behavior).\n> -\t* `print`: Output update-ref commands for pipeline use.\n> ---\n> -+\n> -This setting can be overridden with the `--ref-action` command-line option.\n> -When not configured, `git replay` defaults to `update` mode.\n> +\tSpecifies the default mode for handling reference updates. Either `update` or `print`.\n> +ifdef::git-replay[]\n> +See `--ref-action`.\n> +endif::git-replay[]\n> +ifndef::git-replay[]\n> +See `--ref-action` for linkgit:git-replay[1] for details.\n> +endif::git-replay[]\n\nThis makes it a bit roundabout for \"git config --help\" readers who\nwanted to figure out what value to set to the configuration\nvariable, because the valid choices are no longer listed here.\n\nFinding `--ref-action=` and its description in the other page\nis straight-forward, so it may not be too bad, though.\n\n> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n> index f9ca2db2833..4de85088d6c 100644\n> --- a/Documentation/git-replay.adoc\n> +++ b/Documentation/git-replay.adoc\n> @@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n> \n> CONFIGURATION\n> -------------\n> +:git-replay: 1\n> include::config/replay.adoc[]\n\nThe use of conditional attributes (`ifdef::git-replay[]`) is a neat\nand standard way to tailor the description depending on whether it\nis read as part of `git-config(1)` or `git-replay(1)`. It correctly\npoints the reader to `--ref-action` in the latter case, and provides\na full `linkgit` reference in the former. Clean and correct.\n"},{"id":"544309","messageId":"xmqqtsroed7f.fsf@gitster.g","threadId":"65670","inReplyTo":"--ref-action_definition_list.70c@msgid.xyz","subject":"Re: [PATCH 3/4] doc: replay: use a nested definition list","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-30T22:37:24Z","receivedAt":"2026-05-30T22:37:27Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> This bullet list for `--ref-action` introduces a term with a colon.\n> This is exactly what a definition list is, structurally. Let’s be\n> sylistically consistent and use the definition list markup construct.\n\nMakes sense.\n\n> --\n> -\t* `update` (default): Update refs directly using an atomic transaction.\n> -\t All refs are updated or none are (all-or-nothing behavior).\n> -\t* `print`: Output update-ref commands for pipeline use. This is the\n> -\t traditional behavior where output can be piped to `git update-ref --stdin`.\n> +`update` (default);; Update refs directly using an atomic transaction.\n> +\tAll refs are updated or none are (all-or-nothing behavior).\n> +`print`;; Output update-ref commands for pipeline use. This is the\n> +\ttraditional behavior where output can be piped to `git update-ref --stdin`.\n> --\n> +\n\nThe transition from a bulleted list to a nested definition list\n(`;;`) for the `--ref-action` modes indeed makes the document\nstructure much cleaner.\n\n> The default mode can be configured via the `replay.refAction` configuration variable.\n"},{"id":"544310","messageId":"xmqqpl2ced7d.fsf@gitster.g","threadId":"65670","inReplyTo":"default_RHS.70d@msgid.xyz","subject":"Re: [PATCH 4/4] doc: replay: move “default” to the right-hand-side","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-05-30T22:37:26Z","receivedAt":"2026-05-30T22:37:28Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> -`update` (default);; Update refs directly using an atomic transaction.\n> +`update`;; (default) Update refs directly using an atomic transaction.\n\nThis looks sensible. Nice.\n\n> \tAll refs are updated or none are (all-or-nothing behavior).\n> `print`;; Output update-ref commands for pipeline use. This is the\n> \ttraditional behavior where output can be piped to `git update-ref --stdin`.\n"},{"id":"544493","messageId":"ace3922d-8f73-4a76-944c-f09dfe311db0@app.fastmail.com","threadId":"65670","inReplyTo":"xmqqy0h0ed7h.fsf@gitster.g","subject":"Re: [PATCH 2/4] doc: replay: simplify replay.refAction description","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-02T11:58:22Z","receivedAt":"2026-06-02T11:58:43Z","isPatch":true,"body":"On Sun, May 31, 2026, at 00:37, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> replay.refAction::\n>> -\tSpecifies the default mode for handling reference updates in\n>> -\t`git replay`. The value can be:\n>> -+\n>> ---\n>> -\t* `update`: Update refs directly using an atomic transaction (default behavior).\n>> -\t* `print`: Output update-ref commands for pipeline use.\n>> ---\n>> -+\n>> -This setting can be overridden with the `--ref-action` command-line option.\n>> -When not configured, `git replay` defaults to `update` mode.\n>> +\tSpecifies the default mode for handling reference updates. Either `update` or `print`.\n>> +ifdef::git-replay[]\n>> +See `--ref-action`.\n>> +endif::git-replay[]\n>> +ifndef::git-replay[]\n>> +See `--ref-action` for linkgit:git-replay[1] for details.\n>> +endif::git-replay[]\n>\n> This makes it a bit roundabout for \"git config --help\" readers who\n> wanted to figure out what value to set to the configuration\n> variable, because the valid choices are no longer listed here.\n\nThat’s a good point. My thought process at the time was\n\n• This description list needs to be changed\n• But I also need to change it on git-replay(1)...\n• So why not just gesture towards git-replay(1)?\n\nBut now I see that this does make it slightly worse. Which is not worth\nthe saved effort.\n\nI was thinking that a shared file which is included in the config and\ngit-replay(1) could be used. That file would just contain the definition\nlist. I could also duplicate it manually and leave a comment about\nkeeping them in synch. What do you think?\n\nAssuming that they should be equal, which I think right now although I\nhaven’t started on the next version yet.\n\n>\n> Finding `--ref-action=` and its description in the other page\n> is straight-forward, so it may not be too bad, though.\n>\n>> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n>> index f9ca2db2833..4de85088d6c 100644\n>> --- a/Documentation/git-replay.adoc\n>> +++ b/Documentation/git-replay.adoc\n>> @@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n>>\n>> CONFIGURATION\n>> -------------\n>> +:git-replay: 1\n>> include::config/replay.adoc[]\n>\n> The use of conditional attributes (`ifdef::git-replay[]`) is a neat\n> and standard way to tailor the description depending on whether it\n> is read as part of `git-config(1)` or `git-replay(1)`. It correctly\n> points the reader to `--ref-action` in the latter case, and provides\n> a full `linkgit` reference in the former. Clean and correct.\n\nThanks for the thorough review.\n"},{"id":"544620","messageId":"V2_CV_doc_replay_config.767@msgid.xyz","threadId":"65670","inReplyTo":"CV_doc_replay_config.709@msgid.xyz","subject":"[PATCH v2 0/4] doc: replay: fix config link","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-03T16:04:21Z","receivedAt":"2026-06-03T16:04:36Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied): kh/doc-replay-config\n\nTopic summary: link to the config for git-replay(1) (one variable) in\ngit-replay(1) and git-config(1). Also improve the doc for that config\nvariable and `--ref-action`.\n\n§ Changes in v2\n\nSee the notes on the patches for more points and details.\n\n• Keep the description list for `replay.refAction` (Junio)\n• Add a comment on both description lists about the fact that\n the two are similar\n\n[1/4] doc: link to config for git-replay(1)\n[2/4] doc: replay: improve config description\n[3/4] doc: replay: use a nested description list\n[4/4] doc: replay: move “default” to the right-hand side\n\n Documentation/config.adoc | 2 ++\n Documentation/config/replay.adoc | 19 +++++++++++++------\n Documentation/git-replay.adoc | 16 ++++++++++++----\n 3 files changed, 27 insertions(+), 10 deletions(-)\n\nInterdiff against v1:\ndiff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\nindex 42e521694d1..40d1695782a 100644\n--- a/Documentation/config/replay.adoc\n+++ b/Documentation/config/replay.adoc\n@@ -1,5 +1,15 @@\n replay.refAction::\n-\tSpecifies the default mode for handling reference updates. Either `update` or `print`.\n+\tSpecifies the default mode for handling reference updates.\n+\tThe value can be:\n++\n+--\n+////\n+These use the first sentences from the description list in git-replay(1).\n+////\n+`update`;; (default) Update refs directly using an atomic transaction.\n+`print`;; Output update-ref commands for pipeline use.\n+--\n++\n ifdef::git-replay[]\n See `--ref-action`.\n endif::git-replay[]\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 39ecc2e1876..ea4d14baddb 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -80,6 +80,9 @@ incompatible with `--contained` (which is a modifier for `--onto` only).\n \tControl how references are updated. The mode can be:\n +\n --\n+////\n+Expanded description list compared to 'replay.refAction'.\n+////\n `update`;; (default) Update refs directly using an atomic transaction.\n \tAll refs are updated or none are (all-or-nothing behavior).\n `print`;; Output update-ref commands for pipeline use. This is the\nRange-diff against v1:\n1: ef8212a076a = 1: ef8212a076a doc: link to config for git-replay(1)\n2: 7e915e331b5 ! 2: b60e2e02826 doc: replay: simplify replay.refAction description\n @@ Metadata\n Author: Kristoffer Haugsbakk \n \n ## Commit message ##\n - doc: replay: simplify replay.refAction description\n + doc: replay: improve config description\n \n - We don’t need to list what each argument does since the documentation\n - for `--ref-action` does that. So let’s simplify the `replay.refAction`\n - description by referring to git-replay(1).\n + First of all, this bullet list for `--ref-action` introduces a term with\n + a colon. This is exactly what a description list is, structurally. Let’s\n + be sylistically consistent and use the description list markup\n + construct. Let’s also drop the harmless but unneeded indentation.\n \n - Also make sure to not self-link for the git-replay(1) inclusion.\n + Second, let’s replace the inline-verbatim `git replay` with a link\n + to git-replay(1), since we are naming the command. But make that\n + conditional so that we avoid a self-link inside git-replay(1).[1]\n +\n + † 1: See e.g. e7b3a768 (doc: git-init: rework config item\n + init.templateDir, 2024-03-10) for another example of\n + avoiding self-linking\n \n Signed-off-by: Kristoffer Haugsbakk \n \n @@ Documentation/config/replay.adoc\n replay.refAction::\n -\tSpecifies the default mode for handling reference updates in\n -\t`git replay`. The value can be:\n --+\n ----\n ++\tSpecifies the default mode for handling reference updates.\n ++\tThe value can be:\n + +\n + --\n -\t* `update`: Update refs directly using an atomic transaction (default behavior).\n -\t* `print`: Output update-ref commands for pipeline use.\n ----\n --+\n ++`update`;; Update refs directly using an atomic transaction (default behavior).\n ++`print`;; Output update-ref commands for pipeline use.\n + --\n + +\n -This setting can be overridden with the `--ref-action` command-line option.\n -When not configured, `git replay` defaults to `update` mode.\n -+\tSpecifies the default mode for handling reference updates. Either `update` or `print`.\n +ifdef::git-replay[]\n +See `--ref-action`.\n +endif::git-replay[]\n3: 30952387f35 ! 3: d13cd39cb36 doc: replay: use a nested definition list\n @@ Metadata\n Author: Kristoffer Haugsbakk \n \n ## Commit message ##\n - doc: replay: use a nested definition list\n + doc: replay: use a nested description list\n \n This bullet list for `--ref-action` introduces a term with a colon.\n - This is exactly what a definition list is, structurally. Let’s be\n - sylistically consistent and use the definition list markup construct.\n + This is exactly what a description list is, structurally. Let’s be\n + sylistically consistent and use the desc. list markup construct.[1]\n \n We can reuse the `::` delimiter since we use an open block.\n - But for consistency use the typical nested definition list\n + But for consistency use the typical nested description list\n delimiter, namely `;;`.\n \n Also drop the harmless but unneeded indentation.\n \n + † 1: Same explanation as in the previous commit\n +\n Signed-off-by: Kristoffer Haugsbakk \n \n ## Documentation/git-replay.adoc ##\n4: 71a61bc0ed4 < -: ----------- doc: replay: move “default” to the right-hand-side\n-: ----------- > 4: 17804ea7afa doc: replay: move “default” to the right-hand side\n\nbase-commit: a89346e34a937f001e5d397ee62224e3e9852040\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"544621","messageId":"V2_doc_replay_link_config.768@msgid.xyz","threadId":"65670","inReplyTo":"V2_CV_doc_replay_config.767@msgid.xyz","subject":"[PATCH v2 1/4] doc: link to config for git-replay(1)","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-03T16:04:22Z","receivedAt":"2026-06-03T16:04:55Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis config doc was added in 336ac90c (replay: add replay.refAction\nconfig option, 2025-11-06) but never included anywhere. Include it in\ngit-replay(1) and git-config(1).\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/config.adoc | 2 ++\n Documentation/git-replay.adoc | 4 ++++\n 2 files changed, 6 insertions(+)\n\ndiff --git a/Documentation/config.adoc b/Documentation/config.adoc\nindex 62eebe7c545..51fabecb9b0 100644\n--- a/Documentation/config.adoc\n+++ b/Documentation/config.adoc\n@@ -511,6 +511,8 @@ include::config/remotes.adoc[]\n \n include::config/repack.adoc[]\n \n+include::config/replay.adoc[]\n+\n include::config/rerere.adoc[]\n \n include::config/revert.adoc[]\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex a32f72aead3..f9ca2db2833 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -209,6 +209,10 @@ This replays the range `aabbcc..ddeeff` onto commit `112233` and updates\n `refs/heads/mybranch` to point at the result. This can be useful when you want\n to use bare commit IDs instead of branch names.\n \n+CONFIGURATION\n+-------------\n+include::config/replay.adoc[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"544622","messageId":"V2_doc_replay_improve_config.769@msgid.xyz","threadId":"65670","inReplyTo":"V2_CV_doc_replay_config.767@msgid.xyz","subject":"[PATCH v2 2/4] doc: replay: improve config description","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-03T16:04:23Z","receivedAt":"2026-06-03T16:05:15Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nFirst of all, this bullet list for `--ref-action` introduces a term with\na colon. This is exactly what a description list is, structurally. Let’s\nbe sylistically consistent and use the description list markup\nconstruct. Let’s also drop the harmless but unneeded indentation.\n\nSecond, let’s replace the inline-verbatim `git replay` with a link\nto git-replay(1), since we are naming the command. But make that\nconditional so that we avoid a self-link inside git-replay(1).[1]\n\n† 1: See e.g. e7b3a768 (doc: git-init: rework config item\n init.templateDir, 2024-03-10) for another example of\n avoiding self-linking\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Keep the description list for `replay.refAction` (Junio)\n • Now rewrite the description list like in patch 1/3 (it’s\n technically an unordered list)\n • Msg: mention a previous commit which also avoided self-linking.\n This helps establish a bit more context for why we do this.\n\n Documentation/config/replay.adoc | 16 ++++++++++------\n Documentation/git-replay.adoc | 1 +\n 2 files changed, 11 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\nindex 7d549d2f0e5..7328da9537d 100644\n--- a/Documentation/config/replay.adoc\n+++ b/Documentation/config/replay.adoc\n@@ -1,11 +1,15 @@\n replay.refAction::\n-\tSpecifies the default mode for handling reference updates in\n-\t`git replay`. The value can be:\n+\tSpecifies the default mode for handling reference updates.\n+\tThe value can be:\n +\n --\n-\t* `update`: Update refs directly using an atomic transaction (default behavior).\n-\t* `print`: Output update-ref commands for pipeline use.\n+`update`;; Update refs directly using an atomic transaction (default behavior).\n+`print`;; Output update-ref commands for pipeline use.\n --\n +\n-This setting can be overridden with the `--ref-action` command-line option.\n-When not configured, `git replay` defaults to `update` mode.\n+ifdef::git-replay[]\n+See `--ref-action`.\n+endif::git-replay[]\n+ifndef::git-replay[]\n+See `--ref-action` for linkgit:git-replay[1] for details.\n+endif::git-replay[]\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex f9ca2db2833..4de85088d6c 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n \n CONFIGURATION\n -------------\n+:git-replay: 1\n include::config/replay.adoc[]\n \n GIT\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"544623","messageId":"V2_--ref-action_definition_list.76a@msgid.xyz","threadId":"65670","inReplyTo":"V2_CV_doc_replay_config.767@msgid.xyz","subject":"[PATCH v2 3/4] doc: replay: use a nested description list","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-03T16:04:24Z","receivedAt":"2026-06-03T16:05:33Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis bullet list for `--ref-action` introduces a term with a colon.\nThis is exactly what a description list is, structurally. Let’s be\nsylistically consistent and use the desc. list markup construct.[1]\n\nWe can reuse the `::` delimiter since we use an open block.\nBut for consistency use the typical nested description list\ndelimiter, namely `;;`.\n\nAlso drop the harmless but unneeded indentation.\n\n† 1: Same explanation as in the previous commit\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • Msg: Mention that the explanation for the description list is the\n same as in the previous commit\n • Msg: It’s “description list”, not “definition list”\n\n Documentation/git-replay.adoc | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 4de85088d6c..b4fe43ec687 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -80,10 +80,10 @@ incompatible with `--contained` (which is a modifier for `--onto` only).\n \tControl how references are updated. The mode can be:\n +\n --\n-\t* `update` (default): Update refs directly using an atomic transaction.\n-\t All refs are updated or none are (all-or-nothing behavior).\n-\t* `print`: Output update-ref commands for pipeline use. This is the\n-\t traditional behavior where output can be piped to `git update-ref --stdin`.\n+`update` (default);; Update refs directly using an atomic transaction.\n+\tAll refs are updated or none are (all-or-nothing behavior).\n+`print`;; Output update-ref commands for pipeline use. This is the\n+\ttraditional behavior where output can be piped to `git update-ref --stdin`.\n --\n +\n The default mode can be configured via the `replay.refAction` configuration variable.\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"544624","messageId":"V2_default_RHS.76b@msgid.xyz","threadId":"65670","inReplyTo":"V2_CV_doc_replay_config.767@msgid.xyz","subject":"[PATCH v2 4/4] doc: replay: move “default” to the right-hand side","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-03T16:04:25Z","receivedAt":"2026-06-03T16:05:52Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis is now a description list (see previous commit) and parentheticals\nlike this do not go on the left-hand side. Moving it to the other side\nmakes it stand out just as much and is also more consistent with the\nrest of the documentation.\n\nLet’s also do the same for the `replay.refAction` description list.\nThat makes the two desc. lists identical in the first sentence. Let’s\nadd a comment about that for future editors.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • It’s “description list”, not “definition list”\n • (Same mistake I have done for “line continuation” (it’s “list”))\n • It’s e.g. “right-hand side” (drop “-side” hyphen)\n • Change `replay.refAction` “default” placement\n • Now that these two description lists are so similar, add an\n AsciiDoc comment about it for future editors. Note that I\n outright deleted this list in the previous version because I\n didn’t want to keep them in synch. But we can remain aware of\n these with two comments.\n \n ---\n \n v1:\n > do not go on the left-hand-side.\n \n At least I haven’t seen it.\n\n Documentation/config/replay.adoc | 5 ++++-\n Documentation/git-replay.adoc | 5 ++++-\n 2 files changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\nindex 7328da9537d..40d1695782a 100644\n--- a/Documentation/config/replay.adoc\n+++ b/Documentation/config/replay.adoc\n@@ -3,7 +3,10 @@ replay.refAction::\n \tThe value can be:\n +\n --\n-`update`;; Update refs directly using an atomic transaction (default behavior).\n+////\n+These use the first sentences from the description list in git-replay(1).\n+////\n+`update`;; (default) Update refs directly using an atomic transaction.\n `print`;; Output update-ref commands for pipeline use.\n --\n +\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex b4fe43ec687..ea4d14baddb 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -80,7 +80,10 @@ incompatible with `--contained` (which is a modifier for `--onto` only).\n \tControl how references are updated. The mode can be:\n +\n --\n-`update` (default);; Update refs directly using an atomic transaction.\n+////\n+Expanded description list compared to 'replay.refAction'.\n+////\n+`update`;; (default) Update refs directly using an atomic transaction.\n \tAll refs are updated or none are (all-or-nothing behavior).\n `print`;; Output update-ref commands for pipeline use. This is the\n \ttraditional behavior where output can be piped to `git update-ref --stdin`.\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"544668","messageId":"aiEa5EWeAaaMsqRR@pks.im","threadId":"65670","inReplyTo":"V2_doc_replay_improve_config.769@msgid.xyz","subject":"Re: [PATCH v2 2/4] doc: replay: improve config description","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-04T06:27:48Z","receivedAt":"2026-06-04T06:27:54Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 06:04:23PM +0200, kristofferhaugsbakk@fastmail.com wrote:\n> From: Kristoffer Haugsbakk \n> \n> First of all, this bullet list for `--ref-action` introduces a term with\n> a colon. This is exactly what a description list is, structurally. Let’s\n> be sylistically consistent and use the description list markup\n\ns/sylistically/stylistically/\n\n> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n> index f9ca2db2833..4de85088d6c 100644\n> --- a/Documentation/git-replay.adoc\n> +++ b/Documentation/git-replay.adoc\n> @@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n> \n> CONFIGURATION\n> -------------\n> +:git-replay: 1\n> include::config/replay.adoc[]\n\nNot quite sure, but was this change supposed to be part of the preceding\ncommit, where you also added the include?\n\nPatrick\n"},{"id":"544669","messageId":"fcc2cf52-cb10-4799-a4c9-eb5916187075@app.fastmail.com","threadId":"65670","inReplyTo":"aiEa5EWeAaaMsqRR@pks.im","subject":"Re: [PATCH v2 2/4] doc: replay: improve config description","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-04T06:31:57Z","receivedAt":"2026-06-04T06:32:19Z","isPatch":true,"body":"On Thu, Jun 4, 2026, at 08:27, Patrick Steinhardt wrote:\n> On Wed, Jun 03, 2026 at 06:04:23PM +0200,\n> kristofferhaugsbakk@fastmail.com wrote:\n>> From: Kristoffer Haugsbakk \n>>\n>> First of all, this bullet list for `--ref-action` introduces a term with\n>> a colon. This is exactly what a description list is, structurally. Let’s\n>> be sylistically consistent and use the description list markup\n>\n> s/sylistically/stylistically/\n\nThanks, I’ll make the correction.\n\n>\n>> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n>> index f9ca2db2833..4de85088d6c 100644\n>> --- a/Documentation/git-replay.adoc\n>> +++ b/Documentation/git-replay.adoc\n>> @@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n>>\n>> CONFIGURATION\n>> -------------\n>> +:git-replay: 1\n>> include::config/replay.adoc[]\n>\n> Not quite sure, but was this change supposed to be part of the preceding\n> commit, where you also added the include?\n\nNo, because the conditional is only being put to use now. That was the\nintention anyway. Maybe there is some reason to put it in the first\ncommit?\n\nThanks!\n"},{"id":"544703","messageId":"aiE_yGhjXuTmVHZf@pks.im","threadId":"65670","inReplyTo":"fcc2cf52-cb10-4799-a4c9-eb5916187075@app.fastmail.com","subject":"Re: [PATCH v2 2/4] doc: replay: improve config description","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-04T09:05:12Z","receivedAt":"2026-06-04T09:05:17Z","isPatch":true,"body":"On Thu, Jun 04, 2026 at 08:31:57AM +0200, Kristoffer Haugsbakk wrote:\n> On Thu, Jun 4, 2026, at 08:27, Patrick Steinhardt wrote:\n> > On Wed, Jun 03, 2026 at 06:04:23PM +0200,\n> > kristofferhaugsbakk@fastmail.com wrote:\n> >> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n> >> index f9ca2db2833..4de85088d6c 100644\n> >> --- a/Documentation/git-replay.adoc\n> >> +++ b/Documentation/git-replay.adoc\n> >> @@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n> >>\n> >> CONFIGURATION\n> >> -------------\n> >> +:git-replay: 1\n> >> include::config/replay.adoc[]\n> >\n> > Not quite sure, but was this change supposed to be part of the preceding\n> > commit, where you also added the include?\n> \n> No, because the conditional is only being put to use now. That was the\n> intention anyway. Maybe there is some reason to put it in the first\n> commit?\n\nProbably not. It just read funny, but I guess that it's my ignorance\nabout the adoc format that was also at play here.\n\nPatrick\n"},{"id":"544764","messageId":"13b1ac2e-3790-4553-8e55-5ea2adf8f46a@app.fastmail.com","threadId":"65670","inReplyTo":"xmqqse78fsn2.fsf@gitster.g","subject":"Re: [PATCH 1/4] doc: link to config for git-replay(1)","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-04T20:38:15Z","receivedAt":"2026-06-04T20:38:37Z","isPatch":true,"body":"On Sun, May 31, 2026, at 00:18, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> From: Kristoffer Haugsbakk \n>>\n>> This config doc was added in 336ac90c (replay: add replay.refAction\n>> config option, 2025-11-06) but never included anywhere. Include it in\n>> git-replay(1) and git-config(1).\n>>\n>> Signed-off-by: Kristoffer Haugsbakk \n>> ---\n>> Documentation/config.adoc | 2 ++\n>> Documentation/git-replay.adoc | 4 ++++\n>> 2 files changed, 6 insertions(+)\n>\n> It is always nice to see documentation gaps filled.\n>\n> The `replay.refAction` configuration variable was indeed left\n> dangling without a proper link from the main command documentation,\n> which is embarrassing. I wonder if we can add simple \"doc-lint\"\n> rule or two to prevent similar mistakes from happening again?\n\nFor what it’s worth this is how I found it.\n\nI was working on the kh/doc-hook topic and noticed that my changes\ndidn’t trigger any `doc-diff` changes for git-config(1). So I checked\nthe file and nope, it wasn’t included. Then I massaged the file includes\nand diffed it with `Documentation/config/`. The only missing ones were:\n\n• replay\n• fmt-merge-msg\n\nAnd `fmt-merge-msg` turned out to be a false positive since it is\nincluded via `merge` or something.\n\n>\n>> diff --git a/Documentation/config.adoc b/Documentation/config.adoc\n>> index 62eebe7c545..51fabecb9b0 100644\n>> --- a/Documentation/config.adoc\n>> +++ b/Documentation/config.adoc\n>> @@ -511,6 +511,8 @@ include::config/remotes.adoc[]\n>>[snip]\n"},{"id":"544786","messageId":"V3_CV_doc_replay_config.780@msgid.xyz","threadId":"65670","inReplyTo":"V2_CV_doc_replay_config.767@msgid.xyz","subject":"[PATCH v3 0/4] doc: replay: fix config link","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-05T13:55:58Z","receivedAt":"2026-06-05T13:56:18Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied): kh/doc-replay-config\n\nTopic summary: link to the config for git-replay(1) (one variable) in\ngit-replay(1) and git-config(1). Also improve the doc for that config\nvariable and `--ref-action`.\n\n§ Changes in v3\n\nFix a commit message typo to “stylistically”. Also improve (IMO) the commit\nmessages a bit. See the notes on the patches for details.\n\n§ Link to v2\n\nhttps://lore.kernel.org/git/V2_CV_doc_replay_config.767@msgid.xyz/\n\n[1/4] doc: link to config for git-replay(1)\n[2/4] doc: replay: improve config description\n[3/4] doc: replay: use a nested description list\n[4/4] doc: replay: move “default” to the right-hand side\n\n Documentation/config.adoc | 2 ++\n Documentation/config/replay.adoc | 19 +++++++++++++------\n Documentation/git-replay.adoc | 16 ++++++++++++----\n 3 files changed, 27 insertions(+), 10 deletions(-)\n\nInterdiff against v2:\nRange-diff against v2:\n1: ef8212a076a = 1: ef8212a076a doc: link to config for git-replay(1)\n2: b60e2e02826 ! 2: 35b44b922e5 doc: replay: improve config description\n @@ Metadata\n ## Commit message ##\n doc: replay: improve config description\n \n - First of all, this bullet list for `--ref-action` introduces a term with\n - a colon. This is exactly what a description list is, structurally. Let’s\n - be sylistically consistent and use the description list markup\n - construct. Let’s also drop the harmless but unneeded indentation.\n + First of all, this unordered list for `replay.refAction` introduces\n + a term with a colon. This is exactly what a description list is,\n + structurally. Let’s be stylistically consistent and use the desc.\n + list markup construct. Let’s also drop the harmless but unneeded\n + indentation.\n +\n + We can reuse the `::` delimiter since we use an open block.\n + But for consistency use the typical nested description list\n + delimiter, namely `;;`.\n \n Second, let’s replace the inline-verbatim `git replay` with a link\n to git-replay(1), since we are naming the command. But make that\n3: d13cd39cb36 ! 3: 12c73641fb9 doc: replay: use a nested description list\n @@ Commit message\n \n This bullet list for `--ref-action` introduces a term with a colon.\n This is exactly what a description list is, structurally. Let’s be\n - sylistically consistent and use the desc. list markup construct.[1]\n + stylistically consistent and use the desc. list markup construct.\n \n - We can reuse the `::` delimiter since we use an open block.\n - But for consistency use the typical nested description list\n - delimiter, namely `;;`.\n -\n - Also drop the harmless but unneeded indentation.\n -\n - † 1: Same explanation as in the previous commit\n + In short, just transform this unordered list in the same way that we\n + did for `replay.refAction` in the previous commit.\n \n Signed-off-by: Kristoffer Haugsbakk \n \n4: 17804ea7afa = 4: e2191c723fc doc: replay: move “default” to the right-hand side\n\nbase-commit: a89346e34a937f001e5d397ee62224e3e9852040\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"544787","messageId":"V3_doc_replay_link_config.781@msgid.xyz","threadId":"65670","inReplyTo":"V3_CV_doc_replay_config.780@msgid.xyz","subject":"[PATCH v3 1/4] doc: link to config for git-replay(1)","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-05T13:55:59Z","receivedAt":"2026-06-05T13:56:37Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis config doc was added in 336ac90c (replay: add replay.refAction\nconfig option, 2025-11-06) but never included anywhere. Include it in\ngit-replay(1) and git-config(1).\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/config.adoc | 2 ++\n Documentation/git-replay.adoc | 4 ++++\n 2 files changed, 6 insertions(+)\n\ndiff --git a/Documentation/config.adoc b/Documentation/config.adoc\nindex 62eebe7c545..51fabecb9b0 100644\n--- a/Documentation/config.adoc\n+++ b/Documentation/config.adoc\n@@ -511,6 +511,8 @@ include::config/remotes.adoc[]\n \n include::config/repack.adoc[]\n \n+include::config/replay.adoc[]\n+\n include::config/rerere.adoc[]\n \n include::config/revert.adoc[]\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex a32f72aead3..f9ca2db2833 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -209,6 +209,10 @@ This replays the range `aabbcc..ddeeff` onto commit `112233` and updates\n `refs/heads/mybranch` to point at the result. This can be useful when you want\n to use bare commit IDs instead of branch names.\n \n+CONFIGURATION\n+-------------\n+include::config/replay.adoc[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"544788","messageId":"V3_doc_replay_improve_config.782@msgid.xyz","threadId":"65670","inReplyTo":"V3_CV_doc_replay_config.780@msgid.xyz","subject":"[PATCH v3 2/4] doc: replay: improve config description","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-05T13:56:00Z","receivedAt":"2026-06-05T13:56:56Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nFirst of all, this unordered list for `replay.refAction` introduces\na term with a colon. This is exactly what a description list is,\nstructurally. Let’s be stylistically consistent and use the desc.\nlist markup construct. Let’s also drop the harmless but unneeded\nindentation.\n\nWe can reuse the `::` delimiter since we use an open block.\nBut for consistency use the typical nested description list\ndelimiter, namely `;;`.\n\nSecond, let’s replace the inline-verbatim `git replay` with a link\nto git-replay(1), since we are naming the command. But make that\nconditional so that we avoid a self-link inside git-replay(1).[1]\n\n† 1: See e.g. e7b3a768 (doc: git-init: rework config item\n init.templateDir, 2024-03-10) for another example of\n avoiding self-linking\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v3:\n • Msg:[1] typo, fix to “stylistically”\n • Msg: Move the paragraph about delimiters (;;) from the *next*\n patch over here instead. This is the first place we do it. In the\n next patch we can just say that we are doing the same trans-\n formation as here.\n • Msg: Remove double-space to separate two sentences. That’s\n inconsitent for me. I moved away from that because two-space\n separation takes up too much space when linewrapping is set to 72.\n • Msg: This isn’t the option, it is `replay.refAction`\n • Copy–paste mistake? We don’t have to ask\n • Msg: ... and it’s better to call it an unordered list rather than\n bullet points\n \n † 1: Commit message\n \n ---\n \n v2:\n • Keep the description list for `replay.refAction` (Junio)\n • Now rewrite the description list like in patch 1/3 (it’s\n technically an unordered list)\n • Msg: mention a previous commit which also avoided self-linking.\n This helps establish a bit more context for why we do this.\n\n Documentation/config/replay.adoc | 16 ++++++++++------\n Documentation/git-replay.adoc | 1 +\n 2 files changed, 11 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\nindex 7d549d2f0e5..7328da9537d 100644\n--- a/Documentation/config/replay.adoc\n+++ b/Documentation/config/replay.adoc\n@@ -1,11 +1,15 @@\n replay.refAction::\n-\tSpecifies the default mode for handling reference updates in\n-\t`git replay`. The value can be:\n+\tSpecifies the default mode for handling reference updates.\n+\tThe value can be:\n +\n --\n-\t* `update`: Update refs directly using an atomic transaction (default behavior).\n-\t* `print`: Output update-ref commands for pipeline use.\n+`update`;; Update refs directly using an atomic transaction (default behavior).\n+`print`;; Output update-ref commands for pipeline use.\n --\n +\n-This setting can be overridden with the `--ref-action` command-line option.\n-When not configured, `git replay` defaults to `update` mode.\n+ifdef::git-replay[]\n+See `--ref-action`.\n+endif::git-replay[]\n+ifndef::git-replay[]\n+See `--ref-action` for linkgit:git-replay[1] for details.\n+endif::git-replay[]\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex f9ca2db2833..4de85088d6c 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n \n CONFIGURATION\n -------------\n+:git-replay: 1\n include::config/replay.adoc[]\n \n GIT\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"544789","messageId":"V3_--ref-action_definition_list.783@msgid.xyz","threadId":"65670","inReplyTo":"V3_CV_doc_replay_config.780@msgid.xyz","subject":"[PATCH v3 3/4] doc: replay: use a nested description list","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-05T13:56:01Z","receivedAt":"2026-06-05T13:57:14Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis bullet list for `--ref-action` introduces a term with a colon.\nThis is exactly what a description list is, structurally. Let’s be\nstylistically consistent and use the desc. list markup construct.\n\nIn short, just transform this unordered list in the same way that we\ndid for `replay.refAction` in the previous commit.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v3:\n • Msg:[1] Fix typo: “stylistically”\n • Msg: Simplify message. Devote one paragraph to † 1: Commit\n explain the transformation. Then delegate to the message\n previous patch since we did the same trans-\n formation there.\n \n ---\n \n v2:\n • Msg: Mention that the explanation for the description list is the\n same as in the previous commit\n • Msg: It’s “description list”, not “definition list”\n\n Documentation/git-replay.adoc | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 4de85088d6c..b4fe43ec687 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -80,10 +80,10 @@ incompatible with `--contained` (which is a modifier for `--onto` only).\n \tControl how references are updated. The mode can be:\n +\n --\n-\t* `update` (default): Update refs directly using an atomic transaction.\n-\t All refs are updated or none are (all-or-nothing behavior).\n-\t* `print`: Output update-ref commands for pipeline use. This is the\n-\t traditional behavior where output can be piped to `git update-ref --stdin`.\n+`update` (default);; Update refs directly using an atomic transaction.\n+\tAll refs are updated or none are (all-or-nothing behavior).\n+`print`;; Output update-ref commands for pipeline use. This is the\n+\ttraditional behavior where output can be piped to `git update-ref --stdin`.\n --\n +\n The default mode can be configured via the `replay.refAction` configuration variable.\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"544790","messageId":"V3_default_RHS.784@msgid.xyz","threadId":"65670","inReplyTo":"V3_CV_doc_replay_config.780@msgid.xyz","subject":"[PATCH v3 4/4] doc: replay: move “default” to the right-hand side","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-05T13:56:02Z","receivedAt":"2026-06-05T13:57:33Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis is now a description list (see previous commit) and parentheticals\nlike this do not go on the left-hand side. Moving it to the other side\nmakes it stand out just as much and is also more consistent with the\nrest of the documentation.\n\nLet’s also do the same for the `replay.refAction` description list.\nThat makes the two desc. lists identical in the first sentence. Let’s\nadd a comment about that for future editors.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • It’s “description list”, not “definition list”\n • (Same mistake I have done for “line continuation” (it’s “list”))\n • It’s e.g. “right-hand side” (drop “-side” hyphen)\n • Change `replay.refAction` “default” placement\n • Now that these two description lists are so similar, add an\n AsciiDoc comment about it for future editors. Note that I\n outright deleted this list in the previous version because I\n didn’t want to keep them in synch. But we can remain aware of\n these with two comments.\n \n ---\n \n v1:\n > do not go on the left-hand-side.\n \n At least I haven’t seen it.\n\n Documentation/config/replay.adoc | 5 ++++-\n Documentation/git-replay.adoc | 5 ++++-\n 2 files changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\nindex 7328da9537d..40d1695782a 100644\n--- a/Documentation/config/replay.adoc\n+++ b/Documentation/config/replay.adoc\n@@ -3,7 +3,10 @@ replay.refAction::\n \tThe value can be:\n +\n --\n-`update`;; Update refs directly using an atomic transaction (default behavior).\n+////\n+These use the first sentences from the description list in git-replay(1).\n+////\n+`update`;; (default) Update refs directly using an atomic transaction.\n `print`;; Output update-ref commands for pipeline use.\n --\n +\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex b4fe43ec687..ea4d14baddb 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -80,7 +80,10 @@ incompatible with `--contained` (which is a modifier for `--onto` only).\n \tControl how references are updated. The mode can be:\n +\n --\n-`update` (default);; Update refs directly using an atomic transaction.\n+////\n+Expanded description list compared to 'replay.refAction'.\n+////\n+`update`;; (default) Update refs directly using an atomic transaction.\n \tAll refs are updated or none are (all-or-nothing behavior).\n `print`;; Output update-ref commands for pipeline use. This is the\n \ttraditional behavior where output can be piped to `git update-ref --stdin`.\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"547486","messageId":"87cxwxofgv.fsf@emacs.iotcl.com","threadId":"65670","inReplyTo":"V3_doc_replay_improve_config.782@msgid.xyz","subject":"Re: [PATCH v3 2/4] doc: replay: improve config description","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2026-07-08T12:04:00Z","receivedAt":"2026-07-08T12:04:21Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> First of all, this unordered list for `replay.refAction` introduces\n> a term with a colon. This is exactly what a description list is,\n> structurally. Let’s be stylistically consistent and use the desc.\n> list markup construct. Let’s also drop the harmless but unneeded\n> indentation.\n>\n> We can reuse the `::` delimiter since we use an open block.\n> But for consistency use the typical nested description list\n> delimiter, namely `;;`.\n\nYeah, looking at some other docs (for example\nDocumenation/config/branch.adoc) it makes sense to do it like this.\n\n> Second, let’s replace the inline-verbatim `git replay` with a link\n> to git-replay(1), since we are naming the command. But make that\n> conditional so that we avoid a self-link inside git-replay(1).[1]\n>\n> † 1: See e.g. e7b3a768 (doc: git-init: rework config item\n> init.templateDir, 2024-03-10) for another example of\n> avoiding self-linking\n>\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n>\n> Notes (series):\n> v3:\n> • Msg:[1] typo, fix to “stylistically”\n> • Msg: Move the paragraph about delimiters (;;) from the *next*\n> patch over here instead. This is the first place we do it. In the\n> next patch we can just say that we are doing the same trans-\n> formation as here.\n> • Msg: Remove double-space to separate two sentences. That’s\n> inconsitent for me. I moved away from that because two-space\n> separation takes up too much space when linewrapping is set to 72.\n> • Msg: This isn’t the option, it is `replay.refAction`\n> • Copy–paste mistake? We don’t have to ask\n> • Msg: ... and it’s better to call it an unordered list rather than\n> bullet points\n> \n> † 1: Commit message\n> \n> ---\n> \n> v2:\n> • Keep the description list for `replay.refAction` (Junio)\n> • Now rewrite the description list like in patch 1/3 (it’s\n> technically an unordered list)\n> • Msg: mention a previous commit which also avoided self-linking.\n> This helps establish a bit more context for why we do this.\n>\n> Documentation/config/replay.adoc | 16 ++++++++++------\n> Documentation/git-replay.adoc | 1 +\n> 2 files changed, 11 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\n> index 7d549d2f0e5..7328da9537d 100644\n> --- a/Documentation/config/replay.adoc\n> +++ b/Documentation/config/replay.adoc\n> @@ -1,11 +1,15 @@\n> replay.refAction::\n> -\tSpecifies the default mode for handling reference updates in\n> -\t`git replay`. The value can be:\n> +\tSpecifies the default mode for handling reference updates.\n> +\tThe value can be:\n> +\n> --\n> -\t* `update`: Update refs directly using an atomic transaction (default behavior).\n> -\t* `print`: Output update-ref commands for pipeline use.\n> +`update`;; Update refs directly using an atomic transaction (default behavior).\n> +`print`;; Output update-ref commands for pipeline use.\n> --\n> +\n> -This setting can be overridden with the `--ref-action` command-line option.\n> -When not configured, `git replay` defaults to `update` mode.\n> +ifdef::git-replay[]\n> +See `--ref-action`.\n> +endif::git-replay[]\n> +ifndef::git-replay[]\n> +See `--ref-action` for linkgit:git-replay[1] for details.\n\nI'm not sure about using \"for\" twice, how about:\n\n See `--ref-action` in linkgit:git-replay[1] for details.\n\n> +endif::git-replay[]\n> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n> index f9ca2db2833..4de85088d6c 100644\n> --- a/Documentation/git-replay.adoc\n> +++ b/Documentation/git-replay.adoc\n> @@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n> \n> CONFIGURATION\n> -------------\n> +:git-replay: 1\n> include::config/replay.adoc[]\n> \n> GIT\n> -- \n> 2.54.0.22.g9e26862b904\n>\n>\n\n-- \nCheers,\nToon\n"},{"id":"547488","messageId":"87a4s1of7b.fsf@emacs.iotcl.com","threadId":"65670","inReplyTo":"V3_default_RHS.784@msgid.xyz","subject":"Re: [PATCH v3 4/4] doc: replay: move “default” to the right-hand side","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2026-07-08T12:09:44Z","receivedAt":"2026-07-08T12:09:53Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> This is now a description list (see previous commit) and parentheticals\n> like this do not go on the left-hand side. Moving it to the other side\n> makes it stand out just as much and is also more consistent with the\n> rest of the documentation.\n>\n> Let’s also do the same for the `replay.refAction` description list.\n> That makes the two desc. lists identical in the first sentence. Let’s\n> add a comment about that for future editors.\n\nAh, these quad slashes are comments? Well, that's a thing I've learned\ntoday.\n\nMakes sense.\n\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n>\n> Notes (series):\n> v2:\n> • It’s “description list”, not “definition list”\n> • (Same mistake I have done for “line continuation” (it’s “list”))\n> • It’s e.g. “right-hand side” (drop “-side” hyphen)\n> • Change `replay.refAction` “default” placement\n> • Now that these two description lists are so similar, add an\n> AsciiDoc comment about it for future editors. Note that I\n> outright deleted this list in the previous version because I\n> didn’t want to keep them in synch. But we can remain aware of\n> these with two comments.\n> \n> ---\n> \n> v1:\n> > do not go on the left-hand-side.\n> \n> At least I haven’t seen it.\n>\n> Documentation/config/replay.adoc | 5 ++++-\n> Documentation/git-replay.adoc | 5 ++++-\n> 2 files changed, 8 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\n> index 7328da9537d..40d1695782a 100644\n> --- a/Documentation/config/replay.adoc\n> +++ b/Documentation/config/replay.adoc\n> @@ -3,7 +3,10 @@ replay.refAction::\n> \tThe value can be:\n> +\n> --\n> -`update`;; Update refs directly using an atomic transaction (default behavior).\n> +////\n> +These use the first sentences from the description list in git-replay(1).\n> +////\n> +`update`;; (default) Update refs directly using an atomic transaction.\n> `print`;; Output update-ref commands for pipeline use.\n> --\n> +\n> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n> index b4fe43ec687..ea4d14baddb 100644\n> --- a/Documentation/git-replay.adoc\n> +++ b/Documentation/git-replay.adoc\n> @@ -80,7 +80,10 @@ incompatible with `--contained` (which is a modifier for `--onto` only).\n> \tControl how references are updated. The mode can be:\n> +\n> --\n> -`update` (default);; Update refs directly using an atomic transaction.\n> +////\n> +Expanded description list compared to 'replay.refAction'.\n> +////\n> +`update`;; (default) Update refs directly using an atomic transaction.\n> \tAll refs are updated or none are (all-or-nothing behavior).\n> `print`;; Output update-ref commands for pipeline use. This is the\n> \ttraditional behavior where output can be piped to `git update-ref --stdin`.\n> -- \n> 2.54.0.22.g9e26862b904\n>\n>\n\n-- \nCheers,\nToon\n"},{"id":"548844","messageId":"xmqqv7a5b6n7.fsf@gitster.g","threadId":"65670","inReplyTo":"V3_CV_doc_replay_config.780@msgid.xyz","subject":"Re: [PATCH v3 0/4] doc: replay: fix config link","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-23T23:58:20Z","receivedAt":"2026-07-23T23:58:23Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> Topic name (applied): kh/doc-replay-config\n>\n> Topic summary: link to the config for git-replay(1) (one variable) in\n> git-replay(1) and git-config(1). Also improve the doc for that config\n> variable and `--ref-action`.\n\nI was reviewing the draft of the What's Cooking report and noticed \nthat this topic is among a handful of stalled efforts going nowhere.\n\nIt has been more than a month since this thread got a few good\ncomments by Toon Claes. Would we see an update anytime soon? If\nnot, let me mark the topic to be discarded in my draft of the\nwhats-cooking report.\n\nThanks.\n\n"},{"id":"549281","messageId":"e3bafdc5-2ec8-4023-bd78-46017273c40b@app.fastmail.com","threadId":"65670","inReplyTo":"87cxwxofgv.fsf@emacs.iotcl.com","subject":"Re: [PATCH v3 2/4] doc: replay: improve config description","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:50:24Z","receivedAt":"2026-07-30T09:50:46Z","isPatch":true,"body":"On Wed, Jul 8, 2026, at 14:04, Toon Claes wrote:\n>>[snip]\n>> -This setting can be overridden with the `--ref-action` command-line option.\n>> -When not configured, `git replay` defaults to `update` mode.\n>> +ifdef::git-replay[]\n>> +See `--ref-action`.\n>> +endif::git-replay[]\n>> +ifndef::git-replay[]\n>> +See `--ref-action` for linkgit:git-replay[1] for details.\n>\n> I'm not sure about using \"for\" twice, how about:\n>\n> See `--ref-action` in linkgit:git-replay[1] for details.\n\nThat’s excellent. I’ll use it.\n\nThanks for taking a look!\n\n>\n>> +endif::git-replay[]\n>> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n>> index f9ca2db2833..4de85088d6c 100644\n>> --- a/Documentation/git-replay.adoc\n>> +++ b/Documentation/git-replay.adoc\n>> @@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n>>[snip]\n"},{"id":"549282","messageId":"V4_CV_doc_replay_config.af3@msgid.xyz","threadId":"65670","inReplyTo":"CV_doc_replay_config.709@msgid.xyz","subject":"[PATCH v4 0/4] doc: replay: fix config link","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:57:12Z","receivedAt":"2026-07-30T09:57:39Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied): kh/doc-replay-config\n\nTopic summary: link to the config for git-replay(1) (one variable) in\ngit-replay(1) and git-config(1). Also improve the doc for that config\nvariable and `--ref-action`.\n\n§ Changes in v4\n\nPatch “improve config description”: Take Toon’s suggestion about avoiding\ntwo “for”.\n\n§ Link to v3\n\nhttps://lore.kernel.org/git/V3_CV_doc_replay_config.780@msgid.xyz/\n\n[1/4] doc: link to config for git-replay(1)\n[2/4] doc: replay: improve config description\n[3/4] doc: replay: use a nested description list\n[4/4] doc: replay: move “default” to the right-hand side\n\n Documentation/config.adoc | 2 ++\n Documentation/config/replay.adoc | 19 +++++++++++++------\n Documentation/git-replay.adoc | 16 ++++++++++++----\n 3 files changed, 27 insertions(+), 10 deletions(-)\n\nInterdiff against v3:\ndiff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\nindex 40d1695782a..84e17e313a1 100644\n--- a/Documentation/config/replay.adoc\n+++ b/Documentation/config/replay.adoc\n@@ -14,5 +14,5 @@ ifdef::git-replay[]\n See `--ref-action`.\n endif::git-replay[]\n ifndef::git-replay[]\n-See `--ref-action` for linkgit:git-replay[1] for details.\n+See `--ref-action` in linkgit:git-replay[1] for details.\n endif::git-replay[]\nRange-diff against v3:\n1: ef8212a076a = 1: ef8212a076a doc: link to config for git-replay(1)\n2: 35b44b922e5 ! 2: 392c4f3ab9e doc: replay: improve config description\n @@ Documentation/config/replay.adoc\n +See `--ref-action`.\n +endif::git-replay[]\n +ifndef::git-replay[]\n -+See `--ref-action` for linkgit:git-replay[1] for details.\n ++See `--ref-action` in linkgit:git-replay[1] for details.\n +endif::git-replay[]\n \n ## Documentation/git-replay.adoc ##\n3: 12c73641fb9 = 3: a693ab0b6d3 doc: replay: use a nested description list\n4: e2191c723fc = 4: 53663bd54ed doc: replay: move “default” to the right-hand side\n\nbase-commit: a89346e34a937f001e5d397ee62224e3e9852040\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549283","messageId":"V4_doc_replay_link_config.af4@msgid.xyz","threadId":"65670","inReplyTo":"V4_CV_doc_replay_config.af3@msgid.xyz","subject":"[PATCH v4 1/4] doc: link to config for git-replay(1)","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:57:13Z","receivedAt":"2026-07-30T09:57:57Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis config doc was added in 336ac90c (replay: add replay.refAction\nconfig option, 2025-11-06) but never included anywhere. Include it in\ngit-replay(1) and git-config(1).\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/config.adoc | 2 ++\n Documentation/git-replay.adoc | 4 ++++\n 2 files changed, 6 insertions(+)\n\ndiff --git a/Documentation/config.adoc b/Documentation/config.adoc\nindex 62eebe7c545..51fabecb9b0 100644\n--- a/Documentation/config.adoc\n+++ b/Documentation/config.adoc\n@@ -511,6 +511,8 @@ include::config/remotes.adoc[]\n \n include::config/repack.adoc[]\n \n+include::config/replay.adoc[]\n+\n include::config/rerere.adoc[]\n \n include::config/revert.adoc[]\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex a32f72aead3..f9ca2db2833 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -209,6 +209,10 @@ This replays the range `aabbcc..ddeeff` onto commit `112233` and updates\n `refs/heads/mybranch` to point at the result. This can be useful when you want\n to use bare commit IDs instead of branch names.\n \n+CONFIGURATION\n+-------------\n+include::config/replay.adoc[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549284","messageId":"V4_doc_replay_improve_config.af5@msgid.xyz","threadId":"65670","inReplyTo":"V4_CV_doc_replay_config.af3@msgid.xyz","subject":"[PATCH v4 2/4] doc: replay: improve config description","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:57:14Z","receivedAt":"2026-07-30T09:58:16Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nFirst of all, this unordered list for `replay.refAction` introduces\na term with a colon. This is exactly what a description list is,\nstructurally. Let’s be stylistically consistent and use the desc.\nlist markup construct. Let’s also drop the harmless but unneeded\nindentation.\n\nWe can reuse the `::` delimiter since we use an open block.\nBut for consistency use the typical nested description list\ndelimiter, namely `;;`.\n\nSecond, let’s replace the inline-verbatim `git replay` with a link\nto git-replay(1), since we are naming the command. But make that\nconditional so that we avoid a self-link inside git-replay(1).[1]\n\n† 1: See e.g. e7b3a768 (doc: git-init: rework config item\n init.templateDir, 2024-03-10) for another example of\n avoiding self-linking\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v4:\n • Avoid two “for” in the same sentence; makes the sentence\n flow better\n \n Suggested by Toon: https://lore.kernel.org/git/87cxwxofgv.fsf@emacs.iotcl.com/#t\n \n ---\n \n v3:\n • Msg:[1] typo, fix to “stylistically”\n • Msg: Move the paragraph about delimiters (;;) from the *next*\n patch over here instead. This is the first place we do it. In the\n next patch we can just say that we are doing the same trans-\n formation as here.\n • Msg: Remove double-space to separate two sentences. That’s\n inconsitent for me. I moved away from that because two-space\n separation takes up too much space when linewrapping is set to 72.\n • Msg: This isn’t the option, it is `replay.refAction`\n • Copy–paste mistake? We don’t have to ask\n • Msg: ... and it’s better to call it an unordered list rather than\n bullet points\n \n † 1: Commit message\n \n ---\n \n v2:\n • Keep the description list for `replay.refAction` (Junio)\n • Now rewrite the description list like in patch 1/3 (it’s\n technically an unordered list)\n • Msg: mention a previous commit which also avoided self-linking.\n This helps establish a bit more context for why we do this.\n\n Documentation/config/replay.adoc | 16 ++++++++++------\n Documentation/git-replay.adoc | 1 +\n 2 files changed, 11 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\nindex 7d549d2f0e5..a7dd5288553 100644\n--- a/Documentation/config/replay.adoc\n+++ b/Documentation/config/replay.adoc\n@@ -1,11 +1,15 @@\n replay.refAction::\n-\tSpecifies the default mode for handling reference updates in\n-\t`git replay`. The value can be:\n+\tSpecifies the default mode for handling reference updates.\n+\tThe value can be:\n +\n --\n-\t* `update`: Update refs directly using an atomic transaction (default behavior).\n-\t* `print`: Output update-ref commands for pipeline use.\n+`update`;; Update refs directly using an atomic transaction (default behavior).\n+`print`;; Output update-ref commands for pipeline use.\n --\n +\n-This setting can be overridden with the `--ref-action` command-line option.\n-When not configured, `git replay` defaults to `update` mode.\n+ifdef::git-replay[]\n+See `--ref-action`.\n+endif::git-replay[]\n+ifndef::git-replay[]\n+See `--ref-action` in linkgit:git-replay[1] for details.\n+endif::git-replay[]\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex f9ca2db2833..4de85088d6c 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.\n \n CONFIGURATION\n -------------\n+:git-replay: 1\n include::config/replay.adoc[]\n \n GIT\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549285","messageId":"V4_--ref-action_definition_list.af6@msgid.xyz","threadId":"65670","inReplyTo":"V4_CV_doc_replay_config.af3@msgid.xyz","subject":"[PATCH v4 3/4] doc: replay: use a nested description list","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:57:15Z","receivedAt":"2026-07-30T09:58:34Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis bullet list for `--ref-action` introduces a term with a colon.\nThis is exactly what a description list is, structurally. Let’s be\nstylistically consistent and use the desc. list markup construct.\n\nIn short, just transform this unordered list in the same way that we\ndid for `replay.refAction` in the previous commit.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v3:\n • Msg:[1] Fix typo: “stylistically”\n • Msg: Simplify message. Devote one paragraph to † 1: Commit\n explain the transformation. Then delegate to the message\n previous patch since we did the same trans-\n formation there.\n \n ---\n \n v2:\n • Msg: Mention that the explanation for the description list is the\n same as in the previous commit\n • Msg: It’s “description list”, not “definition list”\n\n Documentation/git-replay.adoc | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 4de85088d6c..b4fe43ec687 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -80,10 +80,10 @@ incompatible with `--contained` (which is a modifier for `--onto` only).\n \tControl how references are updated. The mode can be:\n +\n --\n-\t* `update` (default): Update refs directly using an atomic transaction.\n-\t All refs are updated or none are (all-or-nothing behavior).\n-\t* `print`: Output update-ref commands for pipeline use. This is the\n-\t traditional behavior where output can be piped to `git update-ref --stdin`.\n+`update` (default);; Update refs directly using an atomic transaction.\n+\tAll refs are updated or none are (all-or-nothing behavior).\n+`print`;; Output update-ref commands for pipeline use. This is the\n+\ttraditional behavior where output can be piped to `git update-ref --stdin`.\n --\n +\n The default mode can be configured via the `replay.refAction` configuration variable.\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549286","messageId":"06dacc74-82d9-415a-a5bd-ce6bd824ec0d@app.fastmail.com","threadId":"65670","inReplyTo":"xmqqv7a5b6n7.fsf@gitster.g","subject":"Re: [PATCH v3 0/4] doc: replay: fix config link","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:58:26Z","receivedAt":"2026-07-30T09:58:48Z","isPatch":true,"body":"On Fri, Jul 24, 2026, at 01:58, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> From: Kristoffer Haugsbakk \n>>\n>> Topic name (applied): kh/doc-replay-config\n>>\n>> Topic summary: link to the config for git-replay(1) (one variable) in\n>> git-replay(1) and git-config(1). Also improve the doc for that config\n>> variable and `--ref-action`.\n>\n> I was reviewing the draft of the What's Cooking report and noticed \n> that this topic is among a handful of stalled efforts going nowhere.\n>\n> It has been more than a month since this thread got a few good\n> comments by Toon Claes. Would we see an update anytime soon? If\n> not, let me mark the topic to be discarded in my draft of the\n> whats-cooking report.\n>\n> Thanks.\n\nI have posted a new version now.\n"},{"id":"549287","messageId":"V4_default_RHS.af7@msgid.xyz","threadId":"65670","inReplyTo":"V4_CV_doc_replay_config.af3@msgid.xyz","subject":"[PATCH v4 4/4] doc: replay: move “default” to the right-hand side","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T09:57:16Z","receivedAt":"2026-07-30T09:58:52Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nThis is now a description list (see previous commit) and parentheticals\nlike this do not go on the left-hand side. Moving it to the other side\nmakes it stand out just as much and is also more consistent with the\nrest of the documentation.\n\nLet’s also do the same for the `replay.refAction` description list.\nThat makes the two desc. lists identical in the first sentence. Let’s\nadd a comment about that for future editors.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n • It’s “description list”, not “definition list”\n • (Same mistake I have done for “line continuation” (it’s “list”))\n • It’s e.g. “right-hand side” (drop “-side” hyphen)\n • Change `replay.refAction` “default” placement\n • Now that these two description lists are so similar, add an\n AsciiDoc comment about it for future editors. Note that I\n outright deleted this list in the previous version because I\n didn’t want to keep them in synch. But we can remain aware of\n these with two comments.\n \n ---\n \n v1:\n > do not go on the left-hand-side.\n \n At least I haven’t seen it.\n\n Documentation/config/replay.adoc | 5 ++++-\n Documentation/git-replay.adoc | 5 ++++-\n 2 files changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\nindex a7dd5288553..84e17e313a1 100644\n--- a/Documentation/config/replay.adoc\n+++ b/Documentation/config/replay.adoc\n@@ -3,7 +3,10 @@ replay.refAction::\n \tThe value can be:\n +\n --\n-`update`;; Update refs directly using an atomic transaction (default behavior).\n+////\n+These use the first sentences from the description list in git-replay(1).\n+////\n+`update`;; (default) Update refs directly using an atomic transaction.\n `print`;; Output update-ref commands for pipeline use.\n --\n +\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex b4fe43ec687..ea4d14baddb 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -80,7 +80,10 @@ incompatible with `--contained` (which is a modifier for `--onto` only).\n \tControl how references are updated. The mode can be:\n +\n --\n-`update` (default);; Update refs directly using an atomic transaction.\n+////\n+Expanded description list compared to 'replay.refAction'.\n+////\n+`update`;; (default) Update refs directly using an atomic transaction.\n \tAll refs are updated or none are (all-or-nothing behavior).\n `print`;; Output update-ref commands for pipeline use. This is the\n \ttraditional behavior where output can be piped to `git update-ref --stdin`.\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549310","messageId":"xmqq4ihglab5.fsf@gitster.g","threadId":"65670","inReplyTo":"V4_CV_doc_replay_config.af3@msgid.xyz","subject":"Re: [PATCH v4 0/4] doc: replay: fix config link","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-30T16:19:26Z","receivedAt":"2026-07-30T16:19:29Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> Topic name (applied): kh/doc-replay-config\n>\n> Topic summary: link to the config for git-replay(1) (one variable) in\n> git-replay(1) and git-config(1). Also improve the doc for that config\n> variable and `--ref-action`.\n>\n> § Changes in v4\n>\n> Patch “improve config description”: Take Toon’s suggestion about avoiding\n> two “for”.\n>\n> § Link to v3\n>\n> https://lore.kernel.org/git/V3_CV_doc_replay_config.780@msgid.xyz/\n\nThat's truly minimal update. It is a bit surprising that the topic\nwas stuck for a long time, nearing its expiration date.\n\nA quick look at the thread\nhttps://lore.kernel.org/git/V3_CV_doc_replay_config.780@msgid.xyz/\ntells me that there weren't any outstanding review comments.\n\nThat unfortunately does not say if this version is good enough or\npeople got tired of reviewing and did not pick all lints in v3, but\nwe need to work with what we have, so let's see how smoothly this\nround goes.\n\nWill replace. Thanks.\n\n> [1/4] doc: link to config for git-replay(1)\n> [2/4] doc: replay: improve config description\n> [3/4] doc: replay: use a nested description list\n> [4/4] doc: replay: move “default” to the right-hand side\n>\n> Documentation/config.adoc | 2 ++\n> Documentation/config/replay.adoc | 19 +++++++++++++------\n> Documentation/git-replay.adoc | 16 ++++++++++++----\n> 3 files changed, 27 insertions(+), 10 deletions(-)\n>\n> Interdiff against v3:\n> diff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc\n> index 40d1695782a..84e17e313a1 100644\n> --- a/Documentation/config/replay.adoc\n> +++ b/Documentation/config/replay.adoc\n> @@ -14,5 +14,5 @@ ifdef::git-replay[]\n> See `--ref-action`.\n> endif::git-replay[]\n> ifndef::git-replay[]\n> -See `--ref-action` for linkgit:git-replay[1] for details.\n> +See `--ref-action` in linkgit:git-replay[1] for details.\n> endif::git-replay[]\n> Range-diff against v3:\n> 1: ef8212a076a = 1: ef8212a076a doc: link to config for git-replay(1)\n> 2: 35b44b922e5 ! 2: 392c4f3ab9e doc: replay: improve config description\n> @@ Documentation/config/replay.adoc\n> +See `--ref-action`.\n> +endif::git-replay[]\n> +ifndef::git-replay[]\n> -+See `--ref-action` for linkgit:git-replay[1] for details.\n> ++See `--ref-action` in linkgit:git-replay[1] for details.\n> +endif::git-replay[]\n> \n> ## Documentation/git-replay.adoc ##\n> 3: 12c73641fb9 = 3: a693ab0b6d3 doc: replay: use a nested description list\n> 4: e2191c723fc = 4: 53663bd54ed doc: replay: move “default” to the right-hand side\n>\n> base-commit: a89346e34a937f001e5d397ee62224e3e9852040\n"},{"id":"549311","messageId":"6bcc7490-6dc8-42a7-b3ea-99bf948d7997@app.fastmail.com","threadId":"65670","inReplyTo":"xmqq4ihglab5.fsf@gitster.g","subject":"Re: [PATCH v4 0/4] doc: replay: fix config link","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-30T16:31:24Z","receivedAt":"2026-07-30T16:32:03Z","isPatch":true,"body":"On Thu, Jul 30, 2026, at 18:19, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>>[snip]\n>> § Changes in v4\n>>\n>> Patch “improve config description”: Take Toon’s suggestion about avoiding\n>> two “for”.\n>>\n>> § Link to v3\n>>\n>> https://lore.kernel.org/git/V3_CV_doc_replay_config.780@msgid.xyz/\n>\n> That's truly minimal update. It is a bit surprising that the topic\n> was stuck for a long time, nearing its expiration date.\n>\n> A quick look at the thread\n> https://lore.kernel.org/git/V3_CV_doc_replay_config.780@msgid.xyz/\n> tells me that there weren't any outstanding review comments.\n>\n> That unfortunately does not say if this version is good enough or\n> people got tired of reviewing and did not pick all lints in v3, but\n> we need to work with what we have, so let's see how smoothly this\n> round goes.\n\nYeah, there just hasn’t been much interest in this topic. But thanks\nagain to Toon for taking a fresh look.\n\n>\n> Will replace. Thanks.\n>[snip]\n"},{"id":"549336","messageId":"87h5lfd0oc.fsf@emacs.iotcl.com","threadId":"65670","inReplyTo":"6bcc7490-6dc8-42a7-b3ea-99bf948d7997@app.fastmail.com","subject":"Re: [PATCH v4 0/4] doc: replay: fix config link","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2026-07-31T08:26:59Z","receivedAt":"2026-07-31T08:27:17Z","isPatch":true,"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Thu, Jul 30, 2026, at 18:19, Junio C Hamano wrote:\n>> That's truly minimal update. It is a bit surprising that the topic\n>> was stuck for a long time, nearing its expiration date.\n>>\n>> A quick look at the thread\n>> https://lore.kernel.org/git/V3_CV_doc_replay_config.780@msgid.xyz/\n>> tells me that there weren't any outstanding review comments.\n>>\n>> That unfortunately does not say if this version is good enough or\n>> people got tired of reviewing and did not pick all lints in v3, but\n>> we need to work with what we have, so let's see how smoothly this\n>> round goes.\n>\n> Yeah, there just hasn’t been much interest in this topic. But thanks\n> again to Toon for taking a fresh look.\n>\n>>\n>> Will replace. Thanks.\n>>[snip]\n\nI'm happy with this version too. And for the record, I've locally\nrendered this as it would on git-scm.com, and all look good.\n\n-- \nCheers,\nToon\n"},{"id":"549355","messageId":"xmqq4ihfduxi.fsf@gitster.g","threadId":"65670","inReplyTo":"87h5lfd0oc.fsf@emacs.iotcl.com","subject":"Re: [PATCH v4 0/4] doc: replay: fix config link","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-31T15:45:45Z","receivedAt":"2026-07-31T15:45:48Z","isPatch":true,"body":"Toon Claes writes:\n\n> \"Kristoffer Haugsbakk\" writes:\n>\n>> On Thu, Jul 30, 2026, at 18:19, Junio C Hamano wrote:\n>>> That's truly minimal update. It is a bit surprising that the topic\n>>> was stuck for a long time, nearing its expiration date.\n>>>\n>>> A quick look at the thread\n>>> https://lore.kernel.org/git/V3_CV_doc_replay_config.780@msgid.xyz/\n>>> tells me that there weren't any outstanding review comments.\n>>>\n>>> That unfortunately does not say if this version is good enough or\n>>> people got tired of reviewing and did not pick all lints in v3, but\n>>> we need to work with what we have, so let's see how smoothly this\n>>> round goes.\n>>\n>> Yeah, there just hasn’t been much interest in this topic. But thanks\n>> again to Toon for taking a fresh look.\n>>\n>>>\n>>> Will replace. Thanks.\n>>>[snip]\n>\n> I'm happy with this version too. And for the record, I've locally\n> rendered this as it would on git-scm.com, and all look good.\n\nThanks. Let's mark it for 'next' then.\n\n"}]}