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

> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>>
>> 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.
> 
> 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.