[PATCH 0/4] doc: replay: fix config link

[PATCH 0/4] doc: replay: fix config link

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name: kh/doc-replay-config

Topic summary: link to the config for git-replay(1) (one variable) in
git-replay(1) and git-config(1). Also improve the doc for that config
variable and `--ref-action`.

[1/4] doc: link to config for git-replay(1)
[2/4] doc: replay: simplify replay.refAction description
[3/4] doc: replay: use a nested definition list
[4/4] doc: replay: move “default” to the right-hand-side

 Documentation/config.adoc        |  2 ++
 Documentation/config/replay.adoc | 17 +++++++----------
 Documentation/git-replay.adoc    | 13 +++++++++----
 3 files changed, 18 insertions(+), 14 deletions(-)


base-commit: a89346e34a937f001e5d397ee62224e3e9852040
-- 
2.54.0.13.g9c7419e39f8

[PATCH 1/4] doc: link to config for git-replay(1)

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <code@khaugsbakk.name>
---
 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 62eebe7c545..51fabecb9b0 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 a32f72aead3..f9ca2db2833 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
-- 
2.54.0.13.g9c7419e39f8

[PATCH 2/4] doc: replay: simplify replay.refAction description

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

We don’t need to list what each argument does since the documentation
for `--ref-action` does that. So let’s simplify the `replay.refAction`
description by referring to git-replay(1).

Also make sure to not self-link for the git-replay(1) inclusion.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/config/replay.adoc | 17 +++++++----------
 Documentation/git-replay.adoc    |  1 +
 2 files changed, 8 insertions(+), 10 deletions(-)

diff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc
index 7d549d2f0e5..42e521694d1 100644
--- a/Documentation/config/replay.adoc
+++ b/Documentation/config/replay.adoc
@@ -1,11 +1,8 @@
 replay.refAction::
-	Specifies the default mode for handling reference updates in
-	`git replay`. The value can be:
-+
---
-	* `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.
+	Specifies the default mode for handling reference updates. Either `update` or `print`.
+ifdef::git-replay[]
+See `--ref-action`.
+endif::git-replay[]
+ifndef::git-replay[]
+See `--ref-action` for linkgit:git-replay[1] for details.
+endif::git-replay[]
diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index f9ca2db2833..4de85088d6c 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
-- 
2.54.0.13.g9c7419e39f8

[PATCH 3/4] doc: replay: use a nested definition list

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This bullet list for `--ref-action` introduces a term with a colon.
This is exactly what a definition list is, structurally. Let’s be
sylistically consistent and use the definition list markup construct.

We can reuse the `::` delimiter since we use an open block.
But for consistency use the typical nested definition list
delimiter, namely `;;`.

Also drop the harmless but unneeded indentation.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 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 4de85088d6c..b4fe43ec687 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.
-- 
2.54.0.13.g9c7419e39f8

[PATCH 4/4] doc: replay: move “default” to the right-hand-side

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This is now a definition 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.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    > do not go on the left-hand-side.
    
    At least I haven’t seen it.

 Documentation/git-replay.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index b4fe43ec687..39ecc2e1876 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -80,7 +80,7 @@ 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.
+`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`.
-- 
2.54.0.13.g9c7419e39f8

Re: [PATCH 0/4] doc: replay: fix config link

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> [1/4] doc: link to config for git-replay(1)
> [2/4] doc: replay: simplify replay.refAction description
> [3/4] doc: replay: use a nested definition list
> [4/4] doc: replay: move “default” to the right-hand-side

It is always nice to see documentation gaps filled.

Re: [PATCH 1/4] doc: link to config for git-replay(1)

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> 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 <code@khaugsbakk.name>
> ---
>  Documentation/config.adoc     | 2 ++
>  Documentation/git-replay.adoc | 4 ++++
>  2 files changed, 6 insertions(+)

It is always nice to see documentation gaps filled.

The `replay.refAction` configuration variable was indeed left
dangling without a proper link from the main command documentation,
which is embarrassing.  I wonder if we can add simple "doc-lint"
rule or two to prevent similar mistakes from happening again?

> diff --git a/Documentation/config.adoc b/Documentation/config.adoc
> index 62eebe7c545..51fabecb9b0 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[]

Placing `include::config/replay.adoc[]` in `config.adoc`
alphabetically between `repack` and `rerere` is correct, as the list
is alphabetical.

> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
> index a32f72aead3..f9ca2db2833 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[]
> +

Adding the `CONFIGURATION` section near the end of `git-replay.adoc`
is also the standard way we expose configuration variables to the
command's manual page.

Looking good.

>  GIT
>  ---
>  Part of the linkgit:git[1] suite

Re: [PATCH 2/4] doc: replay: simplify replay.refAction description

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

>  replay.refAction::
> -	Specifies the default mode for handling reference updates in
> -	`git replay`. The value can be:
> -+
> ---
> -	* `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.
> +	Specifies the default mode for handling reference updates. Either `update` or `print`.
> +ifdef::git-replay[]
> +See `--ref-action`.
> +endif::git-replay[]
> +ifndef::git-replay[]
> +See `--ref-action` for linkgit:git-replay[1] for details.
> +endif::git-replay[]

This makes it a bit roundabout for "git config --help" readers who
wanted to figure out what value to set to the configuration
variable, because the valid choices are no longer listed here.

Finding `--ref-action=<mode>` and its description in the other page
is straight-forward, so it may not be too bad, though.

> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
> index f9ca2db2833..4de85088d6c 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[]

The use of conditional attributes (`ifdef::git-replay[]`) is a neat
and standard way to tailor the description depending on whether it
is read as part of `git-config(1)` or `git-replay(1)`. It correctly
points the reader to `--ref-action` in the latter case, and provides
a full `linkgit` reference in the former. Clean and correct.

Re: [PATCH 2/4] doc: replay: simplify replay.refAction description

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

>  replay.refAction::
> -	Specifies the default mode for handling reference updates in
> -	`git replay`. The value can be:
> -+
> ---
> -	* `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.
> +	Specifies the default mode for handling reference updates. Either `update` or `print`.
> +ifdef::git-replay[]
> +See `--ref-action`.
> +endif::git-replay[]
> +ifndef::git-replay[]
> +See `--ref-action` for linkgit:git-replay[1] for details.
> +endif::git-replay[]

This makes it a bit roundabout for "git config --help" readers who
wanted to figure out what value to set to the configuration
variable, because the valid choices are no longer listed here.

Finding `--ref-action=<mode>` and its description in the other page
is straight-forward, so it may not be too bad, though.

> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
> index f9ca2db2833..4de85088d6c 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[]

The use of conditional attributes (`ifdef::git-replay[]`) is a neat
and standard way to tailor the description depending on whether it
is read as part of `git-config(1)` or `git-replay(1)`. It correctly
points the reader to `--ref-action` in the latter case, and provides
a full `linkgit` reference in the former. Clean and correct.

Re: [PATCH 3/4] doc: replay: use a nested definition list

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> This bullet list for `--ref-action` introduces a term with a colon.
> This is exactly what a definition list is, structurally. Let’s be
> sylistically consistent and use the definition list markup construct.

Makes sense.

>  --
> -	* `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 transition from a bulleted list to a nested definition list
(`;;`) for the `--ref-action` modes indeed makes the document
structure much cleaner.

>  The default mode can be configured via the `replay.refAction` configuration variable.

Re: [PATCH 4/4] doc: replay: move “default” to the right-hand-side

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> -`update` (default);; Update refs directly using an atomic transaction.
> +`update`;; (default) Update refs directly using an atomic transaction.

This looks sensible.  Nice.

>  	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`.

Re: [PATCH 2/4] doc: replay: simplify replay.refAction description

[Kristoffer Haugsbakk]

On Sun, May 31, 2026, at 00:37, Junio C Hamano wrote:
> kristofferhaugsbakk@fastmail.com writes:
>
>>  replay.refAction::
>> -	Specifies the default mode for handling reference updates in
>> -	`git replay`. The value can be:
>> -+
>> ---
>> -	* `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.
>> +	Specifies the default mode for handling reference updates. Either `update` or `print`.
>> +ifdef::git-replay[]
>> +See `--ref-action`.
>> +endif::git-replay[]
>> +ifndef::git-replay[]
>> +See `--ref-action` for linkgit:git-replay[1] for details.
>> +endif::git-replay[]
>
> This makes it a bit roundabout for "git config --help" readers who
> wanted to figure out what value to set to the configuration
> variable, because the valid choices are no longer listed here.

That’s a good point. My thought process at the time was

• This description list needs to be changed
• But I also need to change it on git-replay(1)...
• So why not just gesture towards git-replay(1)?

But now I see that this does make it slightly worse. Which is not worth
the saved effort.

I was thinking that a shared file which is included in the config and
git-replay(1) could be used. That file would just contain the definition
list. I could also duplicate it manually and leave a comment about
keeping them in synch. What do you think?

Assuming that they should be equal, which I think right now although I
haven’t started on the next version yet.

>
> Finding `--ref-action=<mode>` and its description in the other page
> is straight-forward, so it may not be too bad, though.
>
>> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
>> index f9ca2db2833..4de85088d6c 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[]
>
> The use of conditional attributes (`ifdef::git-replay[]`) is a neat
> and standard way to tailor the description depending on whether it
> is read as part of `git-config(1)` or `git-replay(1)`. It correctly
> points the reader to `--ref-action` in the latter case, and provides
> a full `linkgit` reference in the former. Clean and correct.

Thanks for the thorough review.

[PATCH v2 0/4] doc: replay: fix config link

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name (applied): kh/doc-replay-config

Topic summary: link to the config for git-replay(1) (one variable) in
git-replay(1) and git-config(1). Also improve the doc for that config
variable and `--ref-action`.

§ Changes in v2

See the notes on the patches for more points and details.

• Keep the description list for `replay.refAction` (Junio)
• Add a comment on both description lists about the fact that
  the two are similar

[1/4] doc: link to config for git-replay(1)
[2/4] doc: replay: improve config description
[3/4] doc: replay: use a nested description list
[4/4] doc: replay: move “default” to the right-hand side

 Documentation/config.adoc        |  2 ++
 Documentation/config/replay.adoc | 19 +++++++++++++------
 Documentation/git-replay.adoc    | 16 ++++++++++++----
 3 files changed, 27 insertions(+), 10 deletions(-)

Interdiff against v1:
diff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc
index 42e521694d1..40d1695782a 100644
--- a/Documentation/config/replay.adoc
+++ b/Documentation/config/replay.adoc
@@ -1,5 +1,15 @@
 replay.refAction::
-	Specifies the default mode for handling reference updates. Either `update` or `print`.
+	Specifies the default mode for handling reference updates.
+	The value can be:
++
+--
+////
+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.
+--
++
 ifdef::git-replay[]
 See `--ref-action`.
 endif::git-replay[]
diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index 39ecc2e1876..ea4d14baddb 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -80,6 +80,9 @@ incompatible with `--contained` (which is a modifier for `--onto` only).
 	Control how references are updated. The mode can be:
 +
 --
+////
+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
Range-diff against v1:
1:  ef8212a076a = 1:  ef8212a076a doc: link to config for git-replay(1)
2:  7e915e331b5 ! 2:  b60e2e02826 doc: replay: simplify replay.refAction description
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: replay: simplify replay.refAction description
    +    doc: replay: improve config description
     
    -    We don’t need to list what each argument does since the documentation
    -    for `--ref-action` does that. So let’s simplify the `replay.refAction`
    -    description by referring to git-replay(1).
    +    First of all, this bullet list for `--ref-action` introduces a term with
    +    a colon.  This is exactly what a description list is, structurally. Let’s
    +    be sylistically consistent and use the description list markup
    +    construct. Let’s also drop the harmless but unneeded indentation.
     
    -    Also make sure to not self-link for the git-replay(1) inclusion.
    +    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 <code@khaugsbakk.name>
     
    @@ Documentation/config/replay.adoc
      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.
    -+	Specifies the default mode for handling reference updates. Either `update` or `print`.
     +ifdef::git-replay[]
     +See `--ref-action`.
     +endif::git-replay[]
3:  30952387f35 ! 3:  d13cd39cb36 doc: replay: use a nested definition list
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: replay: use a nested definition list
    +    doc: replay: use a nested description list
     
         This bullet list for `--ref-action` introduces a term with a colon.
    -    This is exactly what a definition list is, structurally. Let’s be
    -    sylistically consistent and use the definition list markup construct.
    +    This is exactly what a description list is, structurally. Let’s be
    +    sylistically consistent and use the desc. list markup construct.[1]
     
         We can reuse the `::` delimiter since we use an open block.
    -    But for consistency use the typical nested definition list
    +    But for consistency use the typical nested description list
         delimiter, namely `;;`.
     
         Also drop the harmless but unneeded indentation.
     
    +    † 1: Same explanation as in the previous commit
    +
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-replay.adoc ##
4:  71a61bc0ed4 < -:  ----------- doc: replay: move “default” to the right-hand-side
-:  ----------- > 4:  17804ea7afa doc: replay: move “default” to the right-hand side

base-commit: a89346e34a937f001e5d397ee62224e3e9852040
-- 
2.54.0.22.g9e26862b904

[PATCH v2 1/4] doc: link to config for git-replay(1)

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <code@khaugsbakk.name>
---
 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 62eebe7c545..51fabecb9b0 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 a32f72aead3..f9ca2db2833 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
-- 
2.54.0.22.g9e26862b904

[PATCH v2 2/4] doc: replay: improve config description

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

First of all, this bullet list for `--ref-action` introduces a term with
a colon.  This is exactly what a description list is, structurally. Let’s
be sylistically consistent and use the description list markup
construct. Let’s also drop the harmless but unneeded indentation.

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 <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • Keep the description list for `replay.refAction` (Junio)
    • Now rewrite the description list like in patch 1/3 (it’s
      technically an unordered list)
    • Msg: mention a previous commit which also avoided self-linking.
      This helps establish a bit more context for why we do this.

 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 7d549d2f0e5..7328da9537d 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` for linkgit:git-replay[1] for details.
+endif::git-replay[]
diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index f9ca2db2833..4de85088d6c 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
-- 
2.54.0.22.g9e26862b904

[PATCH v2 3/4] doc: replay: use a nested description list

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This bullet list for `--ref-action` introduces a term with a colon.
This is exactly what a description list is, structurally. Let’s be
sylistically consistent and use the desc. list markup construct.[1]

We can reuse the `::` delimiter since we use an open block.
But for consistency use the typical nested description list
delimiter, namely `;;`.

Also drop the harmless but unneeded indentation.

† 1: Same explanation as in the previous commit

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • Msg: Mention that the explanation for the description list is the
      same as in the previous commit
    • Msg: It’s “description list”, not “definition list”

 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 4de85088d6c..b4fe43ec687 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.
-- 
2.54.0.22.g9e26862b904

[PATCH v2 4/4] doc: replay: move “default” to the right-hand side

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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 <code@khaugsbakk.name>
---

Notes (series):
    v2:
    • It’s “description list”, not “definition list”
      • (Same mistake I have done for “line continuation” (it’s “list”))
    • It’s e.g. “right-hand side” (drop “-side” hyphen)
    • Change `replay.refAction` “default” placement
    • Now that these two description lists are so similar, add an
      AsciiDoc comment about it for future editors. Note that I
      outright deleted this list in the previous version because I
      didn’t want to keep them in synch. But we can remain aware of
      these with two comments.
    
    ---
    
    v1:
    > do not go on the left-hand-side.
    
    At least I haven’t seen it.

 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 7328da9537d..40d1695782a 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 b4fe43ec687..ea4d14baddb 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`.
-- 
2.54.0.22.g9e26862b904