From: Phillip Wood <phillip.wood123@gmail•com>
To: Junio C Hamano <gitster@pobox•com>,
Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail•com>
Cc: Phillip Wood <phillip.wood@dunelm•org.uk>,
git@vger•kernel.org,
Christian Couder <christian.couder@gmail•com>,
Elijah Newren <newren@gmail•com>,
Siddharth Asthana <siddharthasthana31@gmail•com>
Subject: Re: [PATCH v2 0/3] doc: replay: improvements like "mention no output on conflicts"
Date: Tue, 16 Dec 2025 14:25:06 +0000 [thread overview]
Message-ID: <df29f24b-f545-47d1-ba4e-9ef25f01934e@gmail.com> (raw)
In-Reply-To: <xmqqa4zj6zhv.fsf@gitster.g>
On 16/12/2025 00:29, Junio C Hamano wrote:
> "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.
That's a good summary of what I found confusing. I like you suggested
message below but I agree it is not worth messing with it now it is in next.
Thanks
Phillip
> 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.
next prev parent reply other threads:[~2025-12-16 14:25 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-12-07 17:55 [PATCH 0/3] doc: replay: improvements like "mention no output on conflicts" kristofferhaugsbakk
2025-12-07 17:55 ` [PATCH 1/3] doc: replay: mention no output on conflicts kristofferhaugsbakk
2025-12-07 17:55 ` [PATCH 2/3] doc: replay: document --contained kristofferhaugsbakk
2025-12-07 17:55 ` [PATCH 3/3] doc: replay: link section using markup kristofferhaugsbakk
2025-12-07 21:58 ` [PATCH 0/3] doc: replay: improvements like "mention no output on conflicts" Junio C Hamano
2025-12-08 7:28 ` Kristoffer Haugsbakk
2025-12-08 12:41 ` Junio C Hamano
2025-12-09 18:05 ` Kristoffer Haugsbakk
2025-12-09 23:02 ` Junio C Hamano
2025-12-08 14:29 ` Toon Claes
2025-12-08 14:35 ` Kristoffer Haugsbakk
2025-12-08 16:00 ` Phillip Wood
2025-12-09 18:03 ` Kristoffer Haugsbakk
2025-12-09 22:57 ` Junio C Hamano
2025-12-10 9:51 ` Phillip Wood
2025-12-10 11:56 ` Junio C Hamano
2025-12-10 12:04 ` Kristoffer Haugsbakk
2025-12-10 14:14 ` Phillip Wood
2025-12-10 15:40 ` Elijah Newren
2025-12-13 13:46 ` [PATCH v2 " kristofferhaugsbakk
2025-12-13 13:46 ` [PATCH v2 1/3] doc: replay: mention no output on conflicts kristofferhaugsbakk
2025-12-13 13:46 ` [PATCH v2 2/3] replay: improve --contained and add to doc kristofferhaugsbakk
2025-12-13 13:46 ` [PATCH v2 3/3] doc: replay: link section using markup kristofferhaugsbakk
2025-12-15 10:13 ` [PATCH v2 0/3] doc: replay: improvements like "mention no output on conflicts" Phillip Wood
2025-12-15 11:59 ` Kristoffer Haugsbakk
2025-12-16 0:29 ` Junio C Hamano
2025-12-16 14:25 ` Phillip Wood [this message]
2025-12-20 19:34 ` Kristoffer Haugsbakk
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=df29f24b-f545-47d1-ba4e-9ef25f01934e@gmail.com \
--to=phillip.wood123@gmail$(echo .)com \
--cc=christian.couder@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=kristofferhaugsbakk@fastmail$(echo .)com \
--cc=newren@gmail$(echo .)com \
--cc=phillip.wood@dunelm$(echo .)org.uk \
--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