From: "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com>
To: "Junio C Hamano" <gitster@pobox•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: Sat, 20 Dec 2025 20:34:37 +0100 [thread overview]
Message-ID: <8e7e09ea-190b-4df6-b013-733334185bb8@app.fastmail.com> (raw)
In-Reply-To: <xmqqa4zj6zhv.fsf@gitster.g>
On Tue, Dec 16, 2025, at 01:29, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com> writes:
>>[snip]
>> 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.
>
>[snip]
> 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.
Oh right, of course. The original area was `doc` and in that case this
would have been fine. But I didn’t consider the `replay` area. So now it
looks like the `--contained` option logic has been changed.
>
> 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.
Okay, now I get it. It turns out I’m still learning how to write commit
messages with the right amount of context.
And thanks to Phillip for confirming.
>[snip]
prev parent reply other threads:[~2025-12-20 19:34 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
2025-12-20 19:34 ` Kristoffer Haugsbakk [this message]
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=8e7e09ea-190b-4df6-b013-733334185bb8@app.fastmail.com \
--to=kristofferhaugsbakk@fastmail$(echo .)com \
--cc=christian.couder@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(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