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

From: "Kristoffer Haugsbakk" <[email-masked]>
Date: Tue, 02 Jun 2026 13:58:22 +0200

On Sun, May 31, 2026, at 00:37, Junio C Hamano wrote:
> [email-masked] 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.