From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 08 Dec 2025 12:41:23 GMT
Subject: Re: [PATCH 0/3] doc: replay: improvements like "mention no output on conflicts"
Message-ID: <xmqqms3tkux8.fsf@gitster.g>
In-Reply-To: <d2a72ba5-ac7c-490f-9f2c-6cf849e65180@app.fastmail.com>

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

> On Sun, Dec 7, 2025, at 22:58, Junio C Hamano wrote:
>> kristofferhaugsbakk@fastmail.com writes:
>>>[snip]
>>> base-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06
>>
>> 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.  For example, I am unsure if somebody who read the document
can accurately answer the following question:

    If you forked 7-commit series from v1.0, merged the early 3
    commits to the 'master' branch, and merged the rest to the
    'next' branch, is that branch contained in 'master..next'?  Or
    it is not because the bottommost 3 commits are not part of
    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?