From: "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com>
To: "Junio C Hamano" <gitster@pobox•com>
Cc: git@vger•kernel.org, "Siddharth Asthana" <siddharthasthana31@gmail•com>
Subject: Re: [PATCH 2/4] doc: replay: simplify replay.refAction description
Date: Tue, 02 Jun 2026 13:58:22 +0200 [thread overview]
Message-ID: <ace3922d-8f73-4a76-944c-f09dfe311db0@app.fastmail.com> (raw)
In-Reply-To: <xmqqy0h0ed7h.fsf@gitster.g>
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.
next prev parent reply other threads:[~2026-06-02 11:58 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-05-21 18:01 [PATCH 0/4] doc: replay: fix config link kristofferhaugsbakk
2026-05-21 18:01 ` [PATCH 1/4] doc: link to config for git-replay(1) kristofferhaugsbakk
2026-05-30 22:18 ` Junio C Hamano
2026-06-04 20:38 ` Kristoffer Haugsbakk
2026-05-21 18:01 ` [PATCH 2/4] doc: replay: simplify replay.refAction description kristofferhaugsbakk
2026-05-30 22:29 ` Junio C Hamano
2026-05-30 22:37 ` Junio C Hamano
2026-06-02 11:58 ` Kristoffer Haugsbakk [this message]
2026-05-21 18:02 ` [PATCH 3/4] doc: replay: use a nested definition list kristofferhaugsbakk
2026-05-30 22:37 ` Junio C Hamano
2026-05-21 18:02 ` [PATCH 4/4] doc: replay: move “default” to the right-hand-side kristofferhaugsbakk
2026-05-30 22:37 ` Junio C Hamano
2026-05-30 22:18 ` [PATCH 0/4] doc: replay: fix config link Junio C Hamano
2026-06-03 16:04 ` [PATCH v2 " kristofferhaugsbakk
2026-06-03 16:04 ` [PATCH v2 1/4] doc: link to config for git-replay(1) kristofferhaugsbakk
2026-06-03 16:04 ` [PATCH v2 2/4] doc: replay: improve config description kristofferhaugsbakk
2026-06-04 6:27 ` Patrick Steinhardt
2026-06-04 6:31 ` Kristoffer Haugsbakk
2026-06-04 9:05 ` Patrick Steinhardt
2026-06-03 16:04 ` [PATCH v2 3/4] doc: replay: use a nested description list kristofferhaugsbakk
2026-06-03 16:04 ` [PATCH v2 4/4] doc: replay: move “default” to the right-hand side kristofferhaugsbakk
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ace3922d-8f73-4a76-944c-f09dfe311db0@app.fastmail.com \
--to=kristofferhaugsbakk@fastmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=siddharthasthana31@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox