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

"Kristoffer Haugsbakk" [off-list ref] writes:

On Mon, Dec 8, 2025, at 13:41, Junio C Hamano wrote:

quoted

quoted

quoted

[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/;-).

quoted

    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.