Skip to contentSkip to conversation

doc: replay: fix config link

PATCH Superseded [email protected] 4 participants 40 messages May 21 – Jul 31 Documentation

lore
Share & tools
lore
#0 lore raw

cover doc: replay: fix config link

From: Kristoffer Haugsbakk <[email protected]>

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

Signature · 1 line
2.54.0.13.g9c7419e39f8
#1 lore raw

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

From: Kristoffer Haugsbakk <[email protected]>

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

---
 Documentation/config.adoc     | 2 ++
 Documentation/git-replay.adoc | 4 ++++
 2 files changed, 6 insertions(+)
Documentation/config.adoc +2 -0
index 62eebe7c545..51fabecb9b0 100644
@@ -511,6 +511,8 @@ include::config/remotes.adoc[]
 
 include::config/repack.adoc[]
 
+include::config/replay.adoc[]
+
 include::config/rerere.adoc[]
 
 include::config/revert.adoc[]
Documentation/git-replay.adoc +4 -0
index a32f72aead3..f9ca2db2833 100644
@@ -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
Signature · 1 line
2.54.0.13.g9c7419e39f8
#2 lore raw

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

Quoted 11 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

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

---
 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?

Documentation/config.adoc include::config/remotes.adoc[] · line 518

Quoted 13 lines
Documentation/config.adoc +2 -0
index 62eebe7c545..51fabecb9b0 100644
@@ -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.

Documentation/git-replay.adoc This replays the range `aabbcc..ddeeff` onto commit `112233` and updates · line 215

Quoted 12 lines
Documentation/git-replay.adoc +4 -0
index a32f72aead3..f9ca2db2833 100644
@@ -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.

Quoted 3 lines
Documentation/git-replay.adoc +0 -0
 GIT
 ---
 Part of the linkgit:git[1] suite
#3 lore raw

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

Quoted 14 lines · Junio C Hamano
Quoted 11 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

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

---
 Documentation/config.adoc     | 2 ++
 Documentation/git-replay.adoc | 4 ++++
 2 files changed, 6 insertions(+)
Quoted 6 lines

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?

For what it’s worth this is how I found it.

I was working on the kh/doc-hook topic and noticed that my changes didn’t trigger any doc-diff changes for git-config(1). So I checked the file and nope, it wasn’t included. Then I massaged the file includes and diffed it with Documentation/config/. The only missing ones were:

• replay
• fmt-merge-msg

And fmt-merge-msg turned out to be a false positive since it is included via merge or something.

Quoted 7 lines
Quoted 7 lines
Documentation/config.adoc +0 -0
index 62eebe7c545..51fabecb9b0 100644
@@ -511,6 +511,8 @@ include::config/remotes.adoc[]
[snip]
#4 lore raw

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

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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.

---
 Documentation/config/replay.adoc | 17 +++++++----------
 Documentation/git-replay.adoc    |  1 +
 2 files changed, 8 insertions(+), 10 deletions(-)
Documentation/config/replay.adoc +7 -10
index 7d549d2f0e5..42e521694d1 100644
@@ -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[]
Documentation/git-replay.adoc +1 -0
index f9ca2db2833..4de85088d6c 100644
@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.
 
 CONFIGURATION
 -------------
+:git-replay: 1
 include::config/replay.adoc[]
 
 GIT
Signature · 1 line
2.54.0.13.g9c7419e39f8
#5 lore raw

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

Quoted 8 lines · [email protected] writes:

replay.refAction::

Documentation/config/replay.adoc +0 -7
-	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.
---

Documentation/config/replay.adoc line 8

Quoted 10 lines
Documentation/config/replay.adoc +7 -3
-+
-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.

Documentation/git-replay.adoc to use bare commit IDs instead of branch names. · line 215

Quoted 10 lines
Documentation/git-replay.adoc +1 -0
index f9ca2db2833..4de85088d6c 100644
@@ -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.

#6 lore raw

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

In reply to [email protected]
Quoted 8 lines · [email protected] writes:

replay.refAction::

Documentation/config/replay.adoc +0 -7
-	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.
---

Documentation/config/replay.adoc line 8

Quoted 10 lines
Documentation/config/replay.adoc +7 -3
-+
-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.

Documentation/git-replay.adoc to use bare commit IDs instead of branch names. · line 215

Quoted 10 lines
Documentation/git-replay.adoc +1 -0
index f9ca2db2833..4de85088d6c 100644
@@ -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.

#7 lore raw

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

Quoted 16 lines · Junio C Hamano
Quoted 14 lines · [email protected] writes:

replay.refAction::

Documentation/config/replay.adoc +3 -10
-	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`.
Quoted 8 lines

Documentation/config/replay.adoc line 8

Quoted 4 lines
Documentation/config/replay.adoc +4 -0
+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.

Quoted 10 lines

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

Quoted 6 lines
Documentation/git-replay.adoc +0 -0
index f9ca2db2833..4de85088d6c 100644
@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.
 
Quoted 10 lines

Documentation/git-replay.adoc to use bare commit IDs instead of branch names. · line 215

Quoted 4 lines
Documentation/git-replay.adoc +1 -0
 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.

#8 lore raw

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

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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.

---
 Documentation/git-replay.adoc | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/git-replay.adoc +4 -4
index 4de85088d6c..b4fe43ec687 100644
@@ -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.
Signature · 1 line
2.54.0.13.g9c7419e39f8
#9 lore raw

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

Quoted 5 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

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.

Documentation/git-replay.adoc incompatible with `--contained` (which is a modifier for `--onto` only). · line 88

Quoted 11 lines

--

Documentation/git-replay.adoc +4 -4
-	* `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.

Quoted 1 line

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

#10 lore raw

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

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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.

---

Notes (series):

Quoted 1 line

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(-)
Documentation/git-replay.adoc +1 -1
index b4fe43ec687..39ecc2e1876 100644
@@ -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`.
Signature · 1 line
2.54.0.13.g9c7419e39f8
#11 lore raw

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

Quoted 2 lines · [email protected] writes:

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

This looks sensible. Nice.

Quoted 3 lines
Documentation/git-replay.adoc +0 -0
 	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`.
#13 lore raw

v2 cover doc: replay: fix config link

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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:

Documentation/config/replay.adoc +11 -1
index 42e521694d1..40d1695782a 100644
@@ -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[]
Documentation/git-replay.adoc +3 -0
index 39ecc2e1876..ea4d14baddb 100644
@@ -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 <[email protected]>

## 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

@@ 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 <[email protected]>

## 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
+

## 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

Signature · 1 line
2.54.0.22.g9e26862b904
#14 lore raw

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

From: Kristoffer Haugsbakk <[email protected]>

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

---
 Documentation/config.adoc     | 2 ++
 Documentation/git-replay.adoc | 4 ++++
 2 files changed, 6 insertions(+)
Documentation/config.adoc +2 -0
index 62eebe7c545..51fabecb9b0 100644
@@ -511,6 +511,8 @@ include::config/remotes.adoc[]
 
 include::config/repack.adoc[]
 
+include::config/replay.adoc[]
+
 include::config/rerere.adoc[]
 
 include::config/revert.adoc[]
Documentation/git-replay.adoc +4 -0
index a32f72aead3..f9ca2db2833 100644
@@ -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
Signature · 1 line
2.54.0.22.g9e26862b904
#15 lore raw

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

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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

---

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(-)
Documentation/config/replay.adoc +10 -6
index 7d549d2f0e5..7328da9537d 100644
@@ -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[]
Documentation/git-replay.adoc +1 -0
index f9ca2db2833..4de85088d6c 100644
@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.
 
 CONFIGURATION
 -------------
+:git-replay: 1
 include::config/replay.adoc[]
 
 GIT
Signature · 1 line
2.54.0.22.g9e26862b904
#16 lore raw

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

Quoted 5 lines · On Wed, Jun 03, 2026 at 06:04:23PM +0200, [email protected]…

From: Kristoffer Haugsbakk <[email protected]>

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

s/sylistically/stylistically/

Documentation/git-replay.adoc to use bare commit IDs instead of branch names. · line 215

Quoted 10 lines
Documentation/git-replay.adoc +1 -0
index f9ca2db2833..4de85088d6c 100644
@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.
 
 CONFIGURATION
 -------------
+:git-replay: 1
 include::config/replay.adoc[]

Not quite sure, but was this change supposed to be part of the preceding commit, where you also added the include?

Patrick

#17 lore raw

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

Quoted 9 lines · Patrick Steinhardt
Quoted 5 lines · On Wed, Jun 03, 2026 at 06:04:23PM +0200, [email protected]…

From: Kristoffer Haugsbakk <[email protected]>

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

s/sylistically/stylistically/

Thanks, I’ll make the correction.

Quoted 7 lines
Quoted 7 lines
Documentation/git-replay.adoc +0 -0
index f9ca2db2833..4de85088d6c 100644
@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.
 
Quoted 7 lines

Documentation/git-replay.adoc to use bare commit IDs instead of branch names. · line 215

Quoted 4 lines
Documentation/git-replay.adoc +1 -0
 CONFIGURATION
 -------------
+:git-replay: 1
 include::config/replay.adoc[]

Not quite sure, but was this change supposed to be part of the preceding commit, where you also added the include?

No, because the conditional is only being put to use now. That was the intention anyway. Maybe there is some reason to put it in the first commit?

Thanks!

#18 lore raw

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

Quoted 17 lines · Kristoffer Haugsbakk
Quoted 8 lines · Patrick Steinhardt
Quoted 6 lines · On Wed, Jun 03, 2026 at 06:04:23PM +0200, [email protected]…
Documentation/git-replay.adoc +0 -0
index f9ca2db2833..4de85088d6c 100644
@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.
 
Quoted 7 lines

Documentation/git-replay.adoc to use bare commit IDs instead of branch names. · line 215

Quoted 4 lines
Documentation/git-replay.adoc +1 -0
 CONFIGURATION
 -------------
+:git-replay: 1
 include::config/replay.adoc[]

Not quite sure, but was this change supposed to be part of the preceding commit, where you also added the include?

Quoted 3 lines

No, because the conditional is only being put to use now. That was the intention anyway. Maybe there is some reason to put it in the first commit?

Probably not. It just read funny, but I guess that it's my ignorance about the adoc format that was also at play here.

Patrick

#19 lore raw

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

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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

---

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(-)
Documentation/git-replay.adoc +4 -4
index 4de85088d6c..b4fe43ec687 100644
@@ -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.
Signature · 1 line
2.54.0.22.g9e26862b904
#20 lore raw

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

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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.

---

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(-)
Documentation/config/replay.adoc +4 -1
index 7328da9537d..40d1695782a 100644
@@ -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.
 --
 +
Documentation/git-replay.adoc +4 -1
index b4fe43ec687..ea4d14baddb 100644
@@ -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`.
Signature · 1 line
2.54.0.22.g9e26862b904
#21 lore raw

v3 cover doc: replay: fix config link

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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 v3

Fix a commit message typo to “stylistically”. Also improve (IMO) the commit messages a bit. See the notes on the patches for details.

§ Link to v2

https://lore.kernel.org/git/[email protected]/

[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 v2:
Range-diff against v2:

1:  ef8212a076a = 1:  ef8212a076a doc: link to config for git-replay(1)
2:  b60e2e02826 ! 2:  35b44b922e5 doc: replay: improve config description

@@ Metadata
## Commit message ##
doc: replay: improve config description

- 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.
+ 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
3: d13cd39cb36 ! 3: 12c73641fb9 doc: replay: use a nested description list
@@ Commit message

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]
+ stylistically consistent and use the desc. list markup construct.

- 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
+ In short, just transform this unordered list in the same way that we
+ did for replay.refAction in the previous commit.

4: 17804ea7afa = 4: e2191c723fc doc: replay: move “default” to the right-hand side

base-commit: a89346e34a937f001e5d397ee62224e3e9852040

Signature · 1 line
2.54.0.22.g9e26862b904
#22 lore raw

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

From: Kristoffer Haugsbakk <[email protected]>

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

---
 Documentation/config.adoc     | 2 ++
 Documentation/git-replay.adoc | 4 ++++
 2 files changed, 6 insertions(+)
Documentation/config.adoc +2 -0
index 62eebe7c545..51fabecb9b0 100644
@@ -511,6 +511,8 @@ include::config/remotes.adoc[]
 
 include::config/repack.adoc[]
 
+include::config/replay.adoc[]
+
 include::config/rerere.adoc[]
 
 include::config/revert.adoc[]
Documentation/git-replay.adoc +4 -0
index a32f72aead3..f9ca2db2833 100644
@@ -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
Signature · 1 line
2.54.0.22.g9e26862b904
#23 lore raw

PATCH v3 2/4 doc: replay: improve config description

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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

---

Notes (series):
v3:
• Msg:[1] typo, fix to “stylistically”
• Msg: Move the paragraph about delimiters (;;) from the *next* patch over here instead. This is the first place we do it. In the next patch we can just say that we are doing the same trans- formation as here.
• Msg: Remove double-space to separate two sentences. That’s inconsitent for me. I moved away from that because two-space separation takes up too much space when linewrapping is set to 72.
• Msg: This isn’t the option, it is replay.refAction
• Copy–paste mistake? We don’t have to ask
• Msg: ... and it’s better to call it an unordered list rather than bullet points

† 1: Commit message

---

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(-)
Documentation/config/replay.adoc +10 -6
index 7d549d2f0e5..7328da9537d 100644
@@ -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[]
Documentation/git-replay.adoc +1 -0
index f9ca2db2833..4de85088d6c 100644
@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.
 
 CONFIGURATION
 -------------
+:git-replay: 1
 include::config/replay.adoc[]
 
 GIT
Signature · 1 line
2.54.0.22.g9e26862b904
#24 lore raw

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

Quoted 11 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

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

Yeah, looking at some other docs (for example Documenation/config/branch.adoc) it makes sense to do it like this.

Quoted 56 lines

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

---

Notes (series):
v3:
• Msg:[1] typo, fix to “stylistically”
• Msg: Move the paragraph about delimiters (;;) from the *next* patch over here instead. This is the first place we do it. In the next patch we can just say that we are doing the same trans- formation as here.
• Msg: Remove double-space to separate two sentences. That’s inconsitent for me. I moved away from that because two-space separation takes up too much space when linewrapping is set to 72.
• Msg: This isn’t the option, it is replay.refAction
• Copy–paste mistake? We don’t have to ask
• Msg: ... and it’s better to call it an unordered list rather than bullet points

† 1: Commit message

---

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(-)
Documentation/config/replay.adoc +3 -4
index 7d549d2f0e5..7328da9537d 100644
@@ -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).

Documentation/config/replay.adoc line 14

Quoted 10 lines
Documentation/config/replay.adoc +6 -2
+`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.

I'm not sure about using "for" twice, how about:

See --ref-action in linkgit:git-replay[1] for details.

Quoted 17 lines
Documentation/config/replay.adoc +1 -0
+endif::git-replay[]
Documentation/git-replay.adoc +1 -0
index f9ca2db2833..4de85088d6c 100644
@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.
 
 CONFIGURATION
 -------------
+:git-replay: 1
 include::config/replay.adoc[]
 
 GIT
Signature · 1 line
2.54.0.22.g9e26862b904
Signature · 2 lines
Cheers,
Toon
#25 lore raw

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

Quoted 11 lines · Toon Claes

Documentation/config/replay.adoc line 14

Quoted 8 lines

[snip]

Documentation/config/replay.adoc +5 -2
-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.

I'm not sure about using "for" twice, how about:

Quoted 1 line

See --ref-action in linkgit:git-replay[1] for details.

That’s excellent. I’ll use it.

Thanks for taking a look!

Quoted 8 lines
Quoted 8 lines
(quoted diff) +1 -0
+endif::git-replay[]
Documentation/git-replay.adoc +0 -0
index f9ca2db2833..4de85088d6c 100644
@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.
[snip]
#26 lore raw

PATCH v3 3/4 doc: replay: use a nested description list

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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.

---

Notes (series):
v3:
• Msg:[1] Fix typo: “stylistically”
• Msg: Simplify message. Devote one paragraph to † 1: Commit
explain the transformation. Then delegate to the message
previous patch since we did the same trans-
formation there.

---

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(-)
Documentation/git-replay.adoc +4 -4
index 4de85088d6c..b4fe43ec687 100644
@@ -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.
Signature · 1 line
2.54.0.22.g9e26862b904
#27 lore raw

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

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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.

---

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(-)
Documentation/config/replay.adoc +4 -1
index 7328da9537d..40d1695782a 100644
@@ -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.
 --
 +
Documentation/git-replay.adoc +4 -1
index b4fe43ec687..ea4d14baddb 100644
@@ -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`.
Signature · 1 line
2.54.0.22.g9e26862b904
#28 lore raw

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

Quoted 10 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

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.

Ah, these quad slashes are comments? Well, that's a thing I've learned today.

Makes sense.

Quoted 62 lines

---

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(-)
Documentation/config/replay.adoc +4 -1
index 7328da9537d..40d1695782a 100644
@@ -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.
 --
 +
Documentation/git-replay.adoc +4 -1
index b4fe43ec687..ea4d14baddb 100644
@@ -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`.
Signature · 1 line
2.54.0.22.g9e26862b904
Signature · 2 lines
Cheers,
Toon
#29 lore raw
In reply to [email protected]
Quoted 7 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

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.

I was reviewing the draft of the What's Cooking report and noticed that this topic is among a handful of stalled efforts going nowhere.

It has been more than a month since this thread got a few good comments by Toon Claes. Would we see an update anytime soon? If not, let me mark the topic to be discarded in my draft of the whats-cooking report.

Thanks.

#30 lore raw
Quoted 13 lines · Junio C Hamano
Quoted 7 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

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.

I was reviewing the draft of the What's Cooking report and noticed that this topic is among a handful of stalled efforts going nowhere.

Quoted 6 lines

It has been more than a month since this thread got a few good comments by Toon Claes. Would we see an update anytime soon? If not, let me mark the topic to be discarded in my draft of the whats-cooking report.

Thanks.

I have posted a new version now.

#31 lore raw

v4 cover doc: replay: fix config link

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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 v4

Patch “improve config description”: Take Toon’s suggestion about avoiding two “for”.

§ Link to v3

https://lore.kernel.org/git/[email protected]/

[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 v3:

Documentation/config/replay.adoc +1 -1
index 40d1695782a..84e17e313a1 100644
@@ -14,5 +14,5 @@ ifdef::git-replay[]
 See `--ref-action`.
 endif::git-replay[]
 ifndef::git-replay[]
-See `--ref-action` for linkgit:git-replay[1] for details.
+See `--ref-action` in linkgit:git-replay[1] for details.
 endif::git-replay[]

Range-diff against v3:

1:  ef8212a076a = 1:  ef8212a076a doc: link to config for git-replay(1)
2:  35b44b922e5 ! 2:  392c4f3ab9e doc: replay: improve config description
    @@ Documentation/config/replay.adoc
     +See `--ref-action`.
     +endif::git-replay[]
     +ifndef::git-replay[]
    -+See `--ref-action` for linkgit:git-replay[1] for details.
    ++See `--ref-action` in linkgit:git-replay[1] for details.
     +endif::git-replay[]
     
      ## Documentation/git-replay.adoc ##
3:  12c73641fb9 = 3:  a693ab0b6d3 doc: replay: use a nested description list
4:  e2191c723fc = 4:  53663bd54ed doc: replay: move “default” to the right-hand side

base-commit: a89346e34a937f001e5d397ee62224e3e9852040

Signature · 1 line
2.54.0.22.g9e26862b904
#32 lore raw

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

From: Kristoffer Haugsbakk <[email protected]>

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

---
 Documentation/config.adoc     | 2 ++
 Documentation/git-replay.adoc | 4 ++++
 2 files changed, 6 insertions(+)
Documentation/config.adoc +2 -0
index 62eebe7c545..51fabecb9b0 100644
@@ -511,6 +511,8 @@ include::config/remotes.adoc[]
 
 include::config/repack.adoc[]
 
+include::config/replay.adoc[]
+
 include::config/rerere.adoc[]
 
 include::config/revert.adoc[]
Documentation/git-replay.adoc +4 -0
index a32f72aead3..f9ca2db2833 100644
@@ -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
Signature · 1 line
2.54.0.22.g9e26862b904
#33 lore raw

PATCH v4 2/4 doc: replay: improve config description

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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

---

Notes (series):
v4:
• Avoid two “for” in the same sentence; makes the sentence flow better

Suggested by Toon: https://lore.kernel.org/git/[email protected]/#t

---

v3:
• Msg:[1] typo, fix to “stylistically”
• Msg: Move the paragraph about delimiters (;;) from the *next* patch over here instead. This is the first place we do it. In the next patch we can just say that we are doing the same trans- formation as here.
• Msg: Remove double-space to separate two sentences. That’s inconsitent for me. I moved away from that because two-space separation takes up too much space when linewrapping is set to 72.
• Msg: This isn’t the option, it is replay.refAction
• Copy–paste mistake? We don’t have to ask
• Msg: ... and it’s better to call it an unordered list rather than bullet points

† 1: Commit message

---

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(-)
Documentation/config/replay.adoc +10 -6
index 7d549d2f0e5..a7dd5288553 100644
@@ -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[]
Documentation/git-replay.adoc +1 -0
index f9ca2db2833..4de85088d6c 100644
@@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names.
 
 CONFIGURATION
 -------------
+:git-replay: 1
 include::config/replay.adoc[]
 
 GIT
Signature · 1 line
2.54.0.22.g9e26862b904
#34 lore raw

PATCH v4 3/4 doc: replay: use a nested description list

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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.

---

Notes (series):
v3:
• Msg:[1] Fix typo: “stylistically”
• Msg: Simplify message. Devote one paragraph to † 1: Commit
explain the transformation. Then delegate to the message
previous patch since we did the same trans-
formation there.

---

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(-)
Documentation/git-replay.adoc +4 -4
index 4de85088d6c..b4fe43ec687 100644
@@ -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.
Signature · 1 line
2.54.0.22.g9e26862b904
#35 lore raw

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

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

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.

---

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(-)
Documentation/config/replay.adoc +4 -1
index a7dd5288553..84e17e313a1 100644
@@ -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.
 --
 +
Documentation/git-replay.adoc +4 -1
index b4fe43ec687..ea4d14baddb 100644
@@ -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`.
Signature · 1 line
2.54.0.22.g9e26862b904
#36 lore raw
In reply to [email protected]
Quoted 8 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

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.

Quoted 8 lines

§ Changes in v4

Patch “improve config description”: Take Toon’s suggestion about avoiding two “for”.

§ Link to v3

https://lore.kernel.org/git/[email protected]/

That's truly minimal update. It is a bit surprising that the topic was stuck for a long time, nearing its expiration date.

A quick look at the thread
https://lore.kernel.org/git/[email protected]/
tells me that there weren't any outstanding review comments.

That unfortunately does not say if this version is good enough or people got tired of reviewing and did not pick all lints in v3, but we need to work with what we have, so let's see how smoothly this round goes.

Will replace. Thanks.

Quoted 38 lines

[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 v3:

Documentation/config/replay.adoc +1 -1
index 40d1695782a..84e17e313a1 100644
@@ -14,5 +14,5 @@ ifdef::git-replay[]
 See `--ref-action`.
 endif::git-replay[]
 ifndef::git-replay[]
-See `--ref-action` for linkgit:git-replay[1] for details.
+See `--ref-action` in linkgit:git-replay[1] for details.
 endif::git-replay[]

Range-diff against v3:

1:  ef8212a076a = 1:  ef8212a076a doc: link to config for git-replay(1)
2:  35b44b922e5 ! 2:  392c4f3ab9e doc: replay: improve config description
    @@ Documentation/config/replay.adoc
     +See `--ref-action`.
     +endif::git-replay[]
     +ifndef::git-replay[]
    -+See `--ref-action` for linkgit:git-replay[1] for details.
    ++See `--ref-action` in linkgit:git-replay[1] for details.
     +endif::git-replay[]
     
      ## Documentation/git-replay.adoc ##
3:  12c73641fb9 = 3:  a693ab0b6d3 doc: replay: use a nested description list
4:  e2191c723fc = 4:  53663bd54ed doc: replay: move “default” to the right-hand side

base-commit: a89346e34a937f001e5d397ee62224e3e9852040

#37 lore raw
Quoted 14 lines · Junio C Hamano
Quoted 9 lines · [email protected] writes:

[snip]
§ Changes in v4

Patch “improve config description”: Take Toon’s suggestion about avoiding two “for”.

§ Link to v3

https://lore.kernel.org/git/[email protected]/

That's truly minimal update. It is a bit surprising that the topic was stuck for a long time, nearing its expiration date.

Quoted 8 lines

A quick look at the thread
https://lore.kernel.org/git/[email protected]/
tells me that there weren't any outstanding review comments.

That unfortunately does not say if this version is good enough or people got tired of reviewing and did not pick all lints in v3, but we need to work with what we have, so let's see how smoothly this round goes.

Yeah, there just hasn’t been much interest in this topic. But thanks again to Toon for taking a fresh look.

Quoted 3 lines

Will replace. Thanks.
[snip]

#38 lore raw
Quoted 8 lines · Kristoffer Haugsbakk
Quoted 7 lines · Junio C Hamano

That's truly minimal update. It is a bit surprising that the topic was stuck for a long time, nearing its expiration date.

A quick look at the thread
https://lore.kernel.org/git/[email protected]/
tells me that there weren't any outstanding review comments.

Quoted 11 lines
Quoted 4 lines

That unfortunately does not say if this version is good enough or people got tired of reviewing and did not pick all lints in v3, but we need to work with what we have, so let's see how smoothly this round goes.

Yeah, there just hasn’t been much interest in this topic. But thanks again to Toon for taking a fresh look.

Quoted 3 lines

Will replace. Thanks.
[snip]

I'm happy with this version too. And for the record, I've locally rendered this as it would on git-scm.com, and all look good.

Signature · 2 lines
Cheers,
Toon
#39 lore raw
Quoted 19 lines · Toon Claes
Quoted 17 lines · Kristoffer Haugsbakk
Quoted 11 lines · Junio C Hamano

That's truly minimal update. It is a bit surprising that the topic was stuck for a long time, nearing its expiration date.

A quick look at the thread
https://lore.kernel.org/git/[email protected]/
tells me that there weren't any outstanding review comments.

That unfortunately does not say if this version is good enough or people got tired of reviewing and did not pick all lints in v3, but we need to work with what we have, so let's see how smoothly this round goes.

Yeah, there just hasn’t been much interest in this topic. But thanks again to Toon for taking a fresh look.

Quoted 1 line
Quoted 5 lines
Quoted 2 lines
Quoted 2 lines

Will replace. Thanks.
[snip]

I'm happy with this version too. And for the record, I've locally rendered this as it would on git-scm.com, and all look good.

Thanks. Let's mark it for 'next' then.