From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Date: Tue, 09 Dec 2025 18:03:51 GMT
Subject: Re: [PATCH 0/3] doc: replay: improvements like "mention no output on conflicts"
Message-ID: <202f7015-1e7f-493e-bd82-474e5cefdf01@app.fastmail.com>
In-Reply-To: <7d0201aa-905c-4da2-932d-47666c923875@gmail.com>

On Mon, Dec 8, 2025, at 17:00, Phillip Wood wrote:
> On 08/12/2025 07:28, Kristoffer Haugsbakk wrote:
>> On Sun, Dec 7, 2025, at 22:58, Junio C Hamano wrote:
>>> kristofferhaugsbakk@fastmail.com writes:
>>>> [snip]
>>>
>>> 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?
>
> Maybe something like
>
>      Update all branches whose head commits are replayed. Requires
>      --onto.

Thanks for the suggestion, and nice catch with the `--onto`. Very
personally I don’t like involving “head” terminology. Both because of
personal biases[1] as well as introducing “head” as a noun in the doc
(now it just talks about `refs/heads/`).

I will discuss the current phrasing “Advance all branches contained in
<revision-range>” in my next email.

† 1: I like the school-of-terminology that says that branches are just a
     particular ref namespace that point to a commit; a branch points to a
     commit, that’s it, that’s all a branch is. Contrast with the
     “branch” gitglossary(7) which says that

         A "branch" is a line of development. The most recent commit on
         a branch is referred to as the tip of that branch. ...

     This is both more involved and causes pedagogical headaches as
     people start wrestling with where a branch “begins” (it is a “line
     of development” after all) in the face of inevitable moves of the
     branch where it started (but the “branch where it started” is of
     course immaterial; it’s the commit that that other branch pointed
     at *at* the time that matters ...) ...