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

From: "Kristoffer Haugsbakk" <[email-masked]>
Date: Tue, 09 Dec 2025 19:05:02 +0100

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.

I read it as this with pseudo-decoration.

    abcde (refs/heads/topic2)
    12345
    56789 (refs/heads/topic1)
    0abcd

`topic1` and `topic2` are contained and will be updated.

> 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'?

I tested that with, let’s say, `topic-1` merged to a `test-master` (and
`topic-2` merged to a `test-next).

`git log test-master..test-next` was as expected (no `topic-1`). Replaying onto
one commit on top of `test-next`:[1]

    $ git replay --contained --onto=test-target test-master..test-next
    <exit code 1>

I guess the “duplicates” (patch-id) cause this?

>     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?

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 ...

And should the description in the source (replay.c) be updated as well?
This goes for Phillip’s point about “Requires --onto” as well.

† 1: By the way: me mistyping `--onto=<branch>` where `<branch>` doesn’t
     exist causes this error:

          fatal: Replaying down to root commit is not supported yet!