From: Kristoffer Haugsbakk Date: Tue, 02 Jun 2026 11:58:22 GMT Subject: Re: [PATCH 2/4] doc: replay: simplify replay.refAction description Message-ID: In-Reply-To: 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=` 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.