From 338765b8a361bec6c45e1df47c9be2dfde45544e Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Thu, 30 Jul 2026 11:57:13 +0200 Subject: [PATCH 1/4] doc: link to config for git-replay(1) This config doc was added in 336ac90c (replay: add replay.refAction config option, 2025-11-06) but never included anywhere. Include it in git-replay(1) and git-config(1). Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/config.adoc | 2 ++ Documentation/git-replay.adoc | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/Documentation/config.adoc b/Documentation/config.adoc index dcea3c0c15..35fc7b4bf6 100644 --- a/Documentation/config.adoc +++ b/Documentation/config.adoc @@ -511,6 +511,8 @@ include::config/remotes.adoc[] include::config/repack.adoc[] +include::config/replay.adoc[] + include::config/rerere.adoc[] include::config/revert.adoc[] diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc index a32f72aead..f9ca2db283 100644 --- a/Documentation/git-replay.adoc +++ b/Documentation/git-replay.adoc @@ -209,6 +209,10 @@ This replays the range `aabbcc..ddeeff` onto commit `112233` and updates `refs/heads/mybranch` to point at the result. This can be useful when you want to use bare commit IDs instead of branch names. +CONFIGURATION +------------- +include::config/replay.adoc[] + GIT --- Part of the linkgit:git[1] suite From 0c93a65ec6cba0305d295bd14e2d286321f1b2ff Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Thu, 30 Jul 2026 11:57:14 +0200 Subject: [PATCH 2/4] doc: replay: improve config description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First of all, this unordered list for `replay.refAction` introduces a term with a colon. This is exactly what a description list is, structurally. Let’s be stylistically consistent and use the desc. list markup construct. Let’s also drop the harmless but unneeded indentation. We can reuse the `::` delimiter since we use an open block. But for consistency use the typical nested description list delimiter, namely `;;`. Second, let’s replace the inline-verbatim `git replay` with a link to git-replay(1), since we are naming the command. But make that conditional so that we avoid a self-link inside git-replay(1).[1] † 1: See e.g. e7b3a768 (doc: git-init: rework config item init.templateDir, 2024-03-10) for another example of avoiding self-linking Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/config/replay.adoc | 16 ++++++++++------ Documentation/git-replay.adoc | 1 + 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc index 7d549d2f0e..a7dd528855 100644 --- a/Documentation/config/replay.adoc +++ b/Documentation/config/replay.adoc @@ -1,11 +1,15 @@ replay.refAction:: - Specifies the default mode for handling reference updates in - `git replay`. The value can be: + Specifies the default mode for handling reference updates. + The value can be: + -- - * `update`: Update refs directly using an atomic transaction (default behavior). - * `print`: Output update-ref commands for pipeline use. +`update`;; Update refs directly using an atomic transaction (default behavior). +`print`;; Output update-ref commands for pipeline use. -- + -This setting can be overridden with the `--ref-action` command-line option. -When not configured, `git replay` defaults to `update` mode. +ifdef::git-replay[] +See `--ref-action`. +endif::git-replay[] +ifndef::git-replay[] +See `--ref-action` in linkgit:git-replay[1] for details. +endif::git-replay[] diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc index f9ca2db283..4de85088d6 100644 --- a/Documentation/git-replay.adoc +++ b/Documentation/git-replay.adoc @@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names. CONFIGURATION ------------- +:git-replay: 1 include::config/replay.adoc[] GIT From dafab0588fd53b3648d66d9add1d6807c89a79ca Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Thu, 30 Jul 2026 11:57:15 +0200 Subject: [PATCH 3/4] doc: replay: use a nested description list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This bullet list for `--ref-action` introduces a term with a colon. This is exactly what a description list is, structurally. Let’s be stylistically consistent and use the desc. list markup construct. In short, just transform this unordered list in the same way that we did for `replay.refAction` in the previous commit. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/git-replay.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc index 4de85088d6..b4fe43ec68 100644 --- a/Documentation/git-replay.adoc +++ b/Documentation/git-replay.adoc @@ -80,10 +80,10 @@ incompatible with `--contained` (which is a modifier for `--onto` only). Control how references are updated. The mode can be: + -- - * `update` (default): Update refs directly using an atomic transaction. - All refs are updated or none are (all-or-nothing behavior). - * `print`: Output update-ref commands for pipeline use. This is the - traditional behavior where output can be piped to `git update-ref --stdin`. +`update` (default);; Update refs directly using an atomic transaction. + All refs are updated or none are (all-or-nothing behavior). +`print`;; Output update-ref commands for pipeline use. This is the + traditional behavior where output can be piped to `git update-ref --stdin`. -- + The default mode can be configured via the `replay.refAction` configuration variable. From 48c0549f5c8b65acc4de91f2233e62b3fc43a644 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Thu, 30 Jul 2026 11:57:16 +0200 Subject: [PATCH 4/4] =?UTF-8?q?doc:=20replay:=20move=20=E2=80=9Cdefault?= =?UTF-8?q?=E2=80=9D=20to=20the=20right-hand=20side?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is now a description list (see previous commit) and parentheticals like this do not go on the left-hand side. Moving it to the other side makes it stand out just as much and is also more consistent with the rest of the documentation. Let’s also do the same for the `replay.refAction` description list. That makes the two desc. lists identical in the first sentence. Let’s add a comment about that for future editors. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- Documentation/config/replay.adoc | 5 ++++- Documentation/git-replay.adoc | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc index a7dd528855..84e17e313a 100644 --- a/Documentation/config/replay.adoc +++ b/Documentation/config/replay.adoc @@ -3,7 +3,10 @@ replay.refAction:: The value can be: + -- -`update`;; Update refs directly using an atomic transaction (default behavior). +//// +These use the first sentences from the description list in git-replay(1). +//// +`update`;; (default) Update refs directly using an atomic transaction. `print`;; Output update-ref commands for pipeline use. -- + diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc index b4fe43ec68..ea4d14badd 100644 --- a/Documentation/git-replay.adoc +++ b/Documentation/git-replay.adoc @@ -80,7 +80,10 @@ incompatible with `--contained` (which is a modifier for `--onto` only). Control how references are updated. The mode can be: + -- -`update` (default);; Update refs directly using an atomic transaction. +//// +Expanded description list compared to 'replay.refAction'. +//// +`update`;; (default) Update refs directly using an atomic transaction. All refs are updated or none are (all-or-nothing behavior). `print`;; Output update-ref commands for pipeline use. This is the traditional behavior where output can be piped to `git update-ref --stdin`.