Re: [PATCH v2 0/3] doc: replay: improvements like "mention no output on conflicts"

[Junio C Hamano <gitster@pobox.com>]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

> On Mon, Dec 15, 2025, at 11:13, Phillip Wood wrote:
>> On 13/12/2025 13:46, kristofferhaugsbakk@fastmail.com wrote:
>>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>>
>>> Explicitly say that conflicts do not give any output. I found this a bit
>>> confusing with the current doc since I am used to other commands
>>> complaining loudly.
>>>
>>> § Changes in v2
>>>
>>> Patch 2/3: improve `--contained` and mention that it requires `--onto`.
>>
>> The new text looks good, I don't really understand the commit message
>> but the intent of the change is clear enough.
>>
>> Thanks for improving the documentation
>
> Thank you. But I’m not glad that the commit message is not clear. I
> would need some guidance on how to write it because it seems clear to
> me. Something with my brain state I guess.

They are already in 'next', but let's see if there are pain points.

commit 8467c95419acaa826a6c1ca0db0f36a3fd614ae4
Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
Date:   Sat Dec 13 14:46:56 2025 +0100

    doc: replay: mention no output on conflicts
    
    Some commands will produce output on stderr if there are conflicts, but
    git-replay(1) is completely silent. Explicitly spell that out.
    
    Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

Looks clear enough to me.


commit 03d7c9c457ba68f28269dcd607b9026ea6c6c9c8
Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
Date:   Sat Dec 13 14:46:57 2025 +0100

    replay: improve --contained and add to doc
    
    There is no documentation for `--contained`.
    
    Start by copying the text from `replay_options` in `builtin/
    replay.c`. But some people think that the existing text is a
    bit unclear; what does it mean for a branch to be contained
    in a revision range? Let’s include the implied commits here:
    the branches that point at commits in the range.
    
    Also use “update” instead of “advance”. “Update” is the verb
    commonly used in this context.
    
    Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
    Helped-by: Junio C Hamano <gitster@pobox.com>
    Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

As to the title, "improve --contained" hinted me there is some code
changes for behaviour, but there isn't, so that part may have been a
bit misleading.  "improve short-help of --contained and add to doc",
perhaps.

I think the problem people found in the second paragraph is because
it is so unclear what it is talking about if you read it without
looking at the patch text.  You started from the existing "advance
all branches contained in revision-range", taken from the existing
short-help in replay_options[].  But without seeing that "branches
contained" text, it is natural that readers find it hard to judge
the validity of "But some people think that..." claim themselves.

If I were writing this (but I will not rewind 'next' to do so),
I'd say something like:

    replay: improve the help of the `--contained` option and document it

    "git replay -h" explains "--contained" as

	advance all branches contained in revision-range

    but it may be unclear when exactly a branch is contained in a
    revision range.  Because the command updates a branch that
    points at a commit that gets rewritten to point at the result of
    the rewrite, "update branches that point at commits in the
    range" says what we want to say more clearly and concisely.

    The "--contained" option has no description in "git replay"
    documentation.  Use the improved phrase there, too.

probably.  In any case, it is a good exercise to see if the proposed
log message can be easily understood without looking at the code
change.


commit 9ba08b30a117e6925a9e5e87c92b37de7396d3a4
Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
Date:   Sat Dec 13 14:46:58 2025 +0100

    doc: replay: link section using markup
    
    Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

Looking good.