git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Toon Claes <toon@iotcl.com>
Date
Jul 8, 2026, 12:04 UTC
Message-ID
<87cxwxofgv.fsf@emacs.iotcl.com>
In-Reply-To
<V3_doc_replay_improve_config.782@msgid.xyz>
kristofferhaugsbakk@fastmail.com writes:
Show 11 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> 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.

Show 66 quoted 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
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>
> 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(-)
>
> 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.
I'm not sure about using "for" twice, how about:
    See `--ref-action` in linkgit:git-replay[1] for details.
Show 17 quoted lines
> +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
>
>
-- 
Cheers,
Toon
Previous: kristofferhaugsbakk@fastmail.comNext: Kristoffer Haugsbakk
Message 25 of 40 in “doc: replay: fix config link”
  1. 0/4 doc: replay: fix config linkkristofferhaugsbakk@fastmail.com, May 21, 2026
  2. 1/4 doc: link to config for git-replay(1)kristofferhaugsbakk@fastmail.com, May 21, 2026
  3. Junio C HamanoMay 30, 2026
  4. Kristoffer HaugsbakkJun 4, 2026
  5. 2/4 doc: replay: simplify replay.refAction descriptionkristofferhaugsbakk@fastmail.com, May 21, 2026
  6. Junio C HamanoMay 30, 2026
  7. Junio C HamanoMay 30, 2026
  8. Kristoffer HaugsbakkJun 2, 2026
  9. 3/4 doc: replay: use a nested definition listkristofferhaugsbakk@fastmail.com, May 21, 2026
  10. Junio C HamanoMay 30, 2026
  11. 4/4 doc: replay: move “default” to the right-hand-sidekristofferhaugsbakk@fastmail.com, May 21, 2026
  12. Junio C HamanoMay 30, 2026
  13. Junio C HamanoMay 30, 2026
  14. 0/4 doc: replay: fix config linkkristofferhaugsbakk@fastmail.com, Jun 3, 2026
  15. 1/4 doc: link to config for git-replay(1)kristofferhaugsbakk@fastmail.com, Jun 3, 2026
  16. 2/4 doc: replay: improve config descriptionkristofferhaugsbakk@fastmail.com, Jun 3, 2026
  17. Patrick SteinhardtJun 4, 2026
  18. Kristoffer HaugsbakkJun 4, 2026
  19. Patrick SteinhardtJun 4, 2026
  20. 3/4 doc: replay: use a nested description listkristofferhaugsbakk@fastmail.com, Jun 3, 2026
  21. 4/4 doc: replay: move “default” to the right-hand sidekristofferhaugsbakk@fastmail.com, Jun 3, 2026
  22. 0/4 doc: replay: fix config linkkristofferhaugsbakk@fastmail.com, Jun 5, 2026
  23. 1/4 doc: link to config for git-replay(1)kristofferhaugsbakk@fastmail.com, Jun 5, 2026
  24. 2/4 doc: replay: improve config descriptionkristofferhaugsbakk@fastmail.com, Jun 5, 2026
  25. Toon ClaesJul 8, 2026
  26. Kristoffer HaugsbakkJul 30, 2026
  27. 3/4 doc: replay: use a nested description listkristofferhaugsbakk@fastmail.com, Jun 5, 2026
  28. 4/4 doc: replay: move “default” to the right-hand sidekristofferhaugsbakk@fastmail.com, Jun 5, 2026
  29. Toon ClaesJul 8, 2026
  30. Junio C HamanoJul 23, 2026
  31. Kristoffer HaugsbakkJul 30, 2026
  32. 0/4 doc: replay: fix config linkkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  33. 1/4 doc: link to config for git-replay(1)kristofferhaugsbakk@fastmail.com, Jul 30, 2026
  34. 2/4 doc: replay: improve config descriptionkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  35. 3/4 doc: replay: use a nested description listkristofferhaugsbakk@fastmail.com, Jul 30, 2026
  36. 4/4 doc: replay: move “default” to the right-hand sidekristofferhaugsbakk@fastmail.com, Jul 30, 2026
  37. Junio C HamanoJul 30, 2026
  38. Kristoffer HaugsbakkJul 30, 2026
  39. Toon ClaesJul 31, 2026
  40. Junio C HamanoJul 31, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.