From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 09 Dec 2025 23:02:34 GMT
Subject: Re: [PATCH 0/3] doc: replay: improvements like "mention no output on conflicts"
Message-ID: <xmqqtsxzi7hx.fsf@gitster.g>
In-Reply-To: <753daaa4-e675-4d28-9c13-4f5ede0f3b47@app.fastmail.com>

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

> On Mon, Dec 8, 2025, at 13:41, Junio C Hamano wrote:
>>>>[snip]
>>>>
>>>> All looked sensible.
>>>>
>>>> The second one looked a bit sketchy, but that was the phrase used by
>>>> the log message for c4611130 (replay: add --contained to rebase
>>>> contained branches, 2023-11-24).
>>>
>>> How should `--contained` be documented?
>>
>> The text you added uses exactly the phrase used by the log message,
>> so the author of the feature apparently felt it is good enough ;-).
>>
>> It just felt that "contained in <revision-range>" is understandable
>> enough.
>
> “is [not]” presumably.

Actually, s/It felt/I was unsure/;-).

>>     master..next?  If it is the former, is it because the topmost
>>     commit (i.e., the commit pointed at by the branch reference) is
>>     the only thing that counts, and it indeed is master..next?
>
> It’s a somewhat complex case compared to what I think is the usual one:
> a non-merge range of commits without any patch-id-equivalents on the
> target (fingers crossed). And the setup without merges: two topic
> branches in the range gives the output I expect:
>
>     git replay --contained --onto=target2 <range>
>     update <top/second>
>     update <bottom/first>
>
> I think the original phrasing is understandable. But we could add
> an example.
>
>     For example, if the range contains five commits where a branch
>     points to the newest commit and another branch points to the third
>     commit ...

Alternatively, you can explicitly refer to "the tip of the branch";
that phrasing will be understood by people from both camps.  Those
who considers that a "branch" consists of the commits between the
fork point and its tip, and those who thinks a "branch" is a fancy
name attached to one particular commit in the DAG that can move
around (typically forward).  Those branches whose tips are within
the range are updated.