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

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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Explicitly say that conflicts do not give any output. I found this a bit
confusing with the current doc since I am used to other commands
complaining loudly.

Also two other things:

Kristoffer Haugsbakk (3):
  doc: replay: mention no output on conflicts
  doc: replay: document --contained
  doc: replay: link section using markup

 Documentation/git-replay.adoc | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)


base-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06
-- 
2.52.0.10.g08704017180

[PATCH 1/3] doc: replay: mention no output on conflicts

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Some commands will produce output on stderr if there are conflicts, but
git-replay(1) is completely silent. Explicitly spell that out.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-replay.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index dcb26e8a8e8..6fbb527b9d8 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -81,6 +81,10 @@ the shape of the history being replayed.  When using `--advance`, the
 number of refs updated is always one, but for `--onto`, it can be one
 or more (rebasing multiple branches simultaneously is supported).
 
+There is no stderr output on conflicts; see the <<exit-status,EXIT
+STATUS>> section below.
+
+[[exit-status]]
 EXIT STATUS
 -----------
 
-- 
2.52.0.10.g08704017180

[PATCH 2/3] doc: replay: document --contained

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Copy the text from `replay_options` in `builtin/replay.c`.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-replay.adoc | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index 6fbb527b9d8..1b8661185bb 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -42,6 +42,9 @@ The history is replayed on top of the <branch> and <branch> is updated to
 point at the tip of the resulting history. This is different from `--onto`,
 which uses the target only as a starting point without updating it.
 
+--contained::
+	Advance all branches contained in <revision-range>.
+
 --ref-action[=<mode>]::
 	Control how references are updated. The mode can be:
 +
-- 
2.52.0.10.g08704017180

[PATCH 3/3] doc: replay: link section using markup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-replay.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index 1b8661185bb..04944a5fa23 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -19,7 +19,7 @@ the working tree and the index untouched. By default, updates the
 relevant references using an atomic transaction (all refs update or
 none). Use `--ref-action=print` to avoid automatic ref updates and
 instead get update commands that can be piped to `git update-ref --stdin`
-(see the OUTPUT section below).
+(see the <<output,OUTPUT>> section below).
 
 THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
 
@@ -66,6 +66,7 @@ The default mode can be configured via the `replay.refAction` configuration vari
 
 include::rev-list-options.adoc[]
 
+[[output]]
 OUTPUT
 ------
 
-- 
2.52.0.10.g08704017180

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

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Explicitly say that conflicts do not give any output. I found this a bit
> confusing with the current doc since I am used to other commands
> complaining loudly.
>
> Also two other things:
>
> Kristoffer Haugsbakk (3):
>   doc: replay: mention no output on conflicts
>   doc: replay: document --contained
>   doc: replay: link section using markup
>
>  Documentation/git-replay.adoc | 10 +++++++++-
>  1 file changed, 9 insertions(+), 1 deletion(-)
>
>
> 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).

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

[Kristoffer Haugsbakk]

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?

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

[Junio C Hamano]

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

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

[Kristoffer Haugsbakk]

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!

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

[Junio C Hamano]

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

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

[Toon Claes]

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

>>> Explicitly say that conflicts do not give any output. I found this a
>>> bit confusing with the current doc since I am used to other commands
>>> complaining loudly.

Yeah I agree it's unusual, and I'm considering to submit patches to
change that behavior. But for now, thanks for adding these docs changes.

> On Sun, Dec 7, 2025, at 22:58, Junio C Hamano wrote:
>>
>> 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?

I understand it might sound a bit cryptic, if you don't have any prior
knowledge about this command. But on the other hand, I don't have any
good idea how you can document this in more detail. I think it's fine
like this.

Overall, I agree with these changes.

-- 
Cheers,
Toon

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

[Kristoffer Haugsbakk]

On Mon, Dec 8, 2025, at 15:29, Toon Claes wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
>>>> Explicitly say that conflicts do not give any output. I found this a
>>>> bit confusing with the current doc since I am used to other commands
>>>> complaining loudly.
>
> Yeah I agree it's unusual, and I'm considering to submit patches to
> change that behavior. But for now, thanks for adding these docs changes.

Thanks for reviewing/checking this out!

>> On Sun, Dec 7, 2025, at 22:58, Junio C Hamano wrote:
>>>
>>> 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?
>
> I understand it might sound a bit cryptic, if you don't have any prior
> knowledge about this command. But on the other hand, I don't have any
> good idea how you can document this in more detail. I think it's fine
> like this.

It sounds like it is the same as `git rebase --update-refs`. I guess
that could be mentioned?

>
> Overall, I agree with these changes.

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

[Phillip Wood]

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

Maybe something like

     Update all branches whose head commits are replayed. Requires
     --onto.

Thanks

Phillip

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

[Kristoffer Haugsbakk]

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

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:

> On Mon, Dec 8, 2025, at 17:00, Phillip Wood wrote:
> ...
>> 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/`).

Yeah, I do not recall calling commit at the tip of a branch a "head
commit".

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

[Phillip Wood]

On 09/12/2025 22:57, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:
> 
>> On Mon, Dec 8, 2025, at 17:00, Phillip Wood wrote:
>> ...
>>> 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/`).
> 
> Yeah, I do not recall calling commit at the tip of a branch a "head
> commit".

We do talk about "branch heads" in our documentation and they point 
commits. We also use "tip" when talking about the commit the branch 
points to so maybe something like

     Update all branches whose tip is replayed

though I think it would be clearer if we could say "commit" somewhere as 
that's what we're replaying. I find the concept of "contained branches" 
rather obscure.

Thanks

Phillip

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

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> writes:

> We do talk about "branch heads" in our documentation and they point 
> commits. We also use "tip" when talking about the commit the branch 
> points to so maybe something like
>
>      Update all branches whose tip is replayed
>
> though I think it would be clearer if we could say "commit" somewhere as 
> that's what we're replaying. I find the concept of "contained branches" 
> rather obscure.

Thanks, I do agree that "branch head", "tip of the branch", etc. can
be used pretty much interchangeably, and using "commit" somwhere
would make it clear.

	Update all branches that point at commits in the replayed
	<revision-range>.

perhaps?  I dunno.

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

[Kristoffer Haugsbakk]

On Wed, Dec 10, 2025, at 12:56, Junio C Hamano wrote:
> Phillip Wood <phillip.wood123@gmail.com> writes:
>
>> We do talk about "branch heads" in our documentation and they point 
>> commits. We also use "tip" when talking about the commit the branch 
>> points to so maybe something like
>>
>>      Update all branches whose tip is replayed
>>
>> though I think it would be clearer if we could say "commit" somewhere as 
>> that's what we're replaying. I find the concept of "contained branches" 
>> rather obscure.
>
> Thanks, I do agree that "branch head", "tip of the branch", etc. can
> be used pretty much interchangeably, and using "commit" somwhere
> would make it clear.
>
> 	Update all branches that point at commits in the replayed
> 	<revision-range>.
>
> perhaps?  I dunno.

I like this. Or just

    Update all branches that point at commits in <revision-range>.

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

[Phillip Wood]

On 10/12/2025 12:04, Kristoffer Haugsbakk wrote:
> On Wed, Dec 10, 2025, at 12:56, Junio C Hamano wrote:
>> Phillip Wood <phillip.wood123@gmail.com> writes:
>>
>>> We do talk about "branch heads" in our documentation and they point
>>> commits. We also use "tip" when talking about the commit the branch
>>> points to so maybe something like
>>>
>>>       Update all branches whose tip is replayed
>>>
>>> though I think it would be clearer if we could say "commit" somewhere as
>>> that's what we're replaying. I find the concept of "contained branches"
>>> rather obscure.
>>
>> Thanks, I do agree that "branch head", "tip of the branch", etc. can
>> be used pretty much interchangeably, and using "commit" somwhere
>> would make it clear.
>>
>> 	Update all branches that point at commits in the replayed
>> 	<revision-range>.
>>
>> perhaps?  I dunno.
> 
> I like this. Or just
> 
>      Update all branches that point at commits in <revision-range>.

I'd be happy with either one

Thanks

Phillip

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

[Elijah Newren]

On Wed, Dec 10, 2025 at 6:14 AM Phillip Wood <phillip.wood123@gmail.com> wrote:
>
> On 10/12/2025 12:04, Kristoffer Haugsbakk wrote:
> > On Wed, Dec 10, 2025, at 12:56, Junio C Hamano wrote:
> >> Phillip Wood <phillip.wood123@gmail.com> writes:
> >>
> >>> We do talk about "branch heads" in our documentation and they point
> >>> commits. We also use "tip" when talking about the commit the branch
> >>> points to so maybe something like
> >>>
> >>>       Update all branches whose tip is replayed
> >>>
> >>> though I think it would be clearer if we could say "commit" somewhere as
> >>> that's what we're replaying. I find the concept of "contained branches"
> >>> rather obscure.
> >>
> >> Thanks, I do agree that "branch head", "tip of the branch", etc. can
> >> be used pretty much interchangeably, and using "commit" somwhere
> >> would make it clear.
> >>
> >>      Update all branches that point at commits in the replayed
> >>      <revision-range>.
> >>
> >> perhaps?  I dunno.
> >
> > I like this. Or just
> >
> >      Update all branches that point at commits in <revision-range>.
>
> I'd be happy with either one

Same.

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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Explicitly say that conflicts do not give any output. I found this a bit
confusing with the current doc since I am used to other commands
complaining loudly.

§ Changes in v2

Patch 2/3: improve `--contained` and mention that it requires `--onto`.

Kristoffer Haugsbakk (3):
  doc: replay: mention no output on conflicts
  replay: improve --contained and add to doc
  doc: replay: link section using markup

 Documentation/git-replay.adoc | 11 ++++++++++-
 builtin/replay.c              |  2 +-
 2 files changed, 11 insertions(+), 2 deletions(-)

Interdiff against v1:
diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index 04944a5fa23..22fd1b271af 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -43,7 +43,8 @@ point at the tip of the resulting history. This is different from `--onto`,
 which uses the target only as a starting point without updating it.
 
 --contained::
-	Advance all branches contained in <revision-range>.
+	Update all branches that point at commits in
+	<revision-range>. Requires `--onto`.
 
 --ref-action[=<mode>]::
 	Control how references are updated. The mode can be:
diff --git a/builtin/replay.c b/builtin/replay.c
index 6606a2c94bc..9e5ad64cad6 100644
--- a/builtin/replay.c
+++ b/builtin/replay.c
@@ -377,7 +377,7 @@ int cmd_replay(int argc,
 			   N_("revision"),
 			   N_("replay onto given commit")),
 		OPT_BOOL(0, "contained", &contained,
-			 N_("advance all branches contained in revision-range")),
+			 N_("update all branches that point at commits in <revision-range>")),
 		OPT_STRING(0, "ref-action", &ref_action,
 			   N_("mode"),
 			   N_("control ref update behavior (update|print)")),
Range-diff against v1:
1:  b9ec24c8b8f = 1:  b9ec24c8b8f doc: replay: mention no output on conflicts
2:  02a80ee87b5 ! 2:  27bf2ac7a0b doc: replay: document --contained
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: replay: document --contained
    +    replay: improve --contained and add to doc
     
    -    Copy the text from `replay_options` in `builtin/replay.c`.
    +    There is no documentation for `--contained`.
     
    +    Start by copying the text from `replay_options` in `builtin/
    +    replay.c`. But some people think that the existing text is a
    +    bit unclear; what does it mean for a branch to be contained
    +    in a revision range? Let’s include the implied commits here:
    +    the branches that point at commits in the range.
    +
    +    Also use “update” instead of “advance”. “Update” is the verb
    +    commonly used in this context.
    +
    +    Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
    +    Helped-by: Junio C Hamano <gitster@pobox.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +
    +    Don’t just copy `--contained` over. Improve it on both sites after discussing
    +    with reviewers.
    +
    +    Also mention that `--onto` is required.
    +
      ## Documentation/git-replay.adoc ##
     @@ Documentation/git-replay.adoc: The history is replayed on top of the <branch> and <branch> is updated to
      point at the tip of the resulting history. This is different from `--onto`,
      which uses the target only as a starting point without updating it.
      
     +--contained::
    -+	Advance all branches contained in <revision-range>.
    ++	Update all branches that point at commits in
    ++	<revision-range>. Requires `--onto`.
     +
      --ref-action[=<mode>]::
      	Control how references are updated. The mode can be:
      +
    +
    + ## builtin/replay.c ##
    +@@ builtin/replay.c: int cmd_replay(int argc,
    + 			   N_("revision"),
    + 			   N_("replay onto given commit")),
    + 		OPT_BOOL(0, "contained", &contained,
    +-			 N_("advance all branches contained in revision-range")),
    ++			 N_("update all branches that point at commits in <revision-range>")),
    + 		OPT_STRING(0, "ref-action", &ref_action,
    + 			   N_("mode"),
    + 			   N_("control ref update behavior (update|print)")),
3:  ca83b00343d = 3:  4e851fdff34 doc: replay: link section using markup

base-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06
-- 
2.52.0.10.g08704017180

[PATCH v2 1/3] doc: replay: mention no output on conflicts

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Some commands will produce output on stderr if there are conflicts, but
git-replay(1) is completely silent. Explicitly spell that out.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-replay.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index dcb26e8a8e8..6fbb527b9d8 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -81,6 +81,10 @@ the shape of the history being replayed.  When using `--advance`, the
 number of refs updated is always one, but for `--onto`, it can be one
 or more (rebasing multiple branches simultaneously is supported).
 
+There is no stderr output on conflicts; see the <<exit-status,EXIT
+STATUS>> section below.
+
+[[exit-status]]
 EXIT STATUS
 -----------
 
-- 
2.52.0.10.g08704017180

[PATCH v2 2/3] replay: improve --contained and add to doc

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

There is no documentation for `--contained`.

Start by copying the text from `replay_options` in `builtin/
replay.c`. But some people think that the existing text is a
bit unclear; what does it mean for a branch to be contained
in a revision range? Let’s include the implied commits here:
the branches that point at commits in the range.

Also use “update” instead of “advance”. “Update” is the verb
commonly used in this context.

Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    
    Don’t just copy `--contained` over. Improve it on both sites after discussing
    with reviewers.
    
    Also mention that `--onto` is required.

 Documentation/git-replay.adoc | 4 ++++
 builtin/replay.c              | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index 6fbb527b9d8..1e2469b9034 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -42,6 +42,10 @@ The history is replayed on top of the <branch> and <branch> is updated to
 point at the tip of the resulting history. This is different from `--onto`,
 which uses the target only as a starting point without updating it.
 
+--contained::
+	Update all branches that point at commits in
+	<revision-range>. Requires `--onto`.
+
 --ref-action[=<mode>]::
 	Control how references are updated. The mode can be:
 +
diff --git a/builtin/replay.c b/builtin/replay.c
index 6606a2c94bc..9e5ad64cad6 100644
--- a/builtin/replay.c
+++ b/builtin/replay.c
@@ -377,7 +377,7 @@ int cmd_replay(int argc,
 			   N_("revision"),
 			   N_("replay onto given commit")),
 		OPT_BOOL(0, "contained", &contained,
-			 N_("advance all branches contained in revision-range")),
+			 N_("update all branches that point at commits in <revision-range>")),
 		OPT_STRING(0, "ref-action", &ref_action,
 			   N_("mode"),
 			   N_("control ref update behavior (update|print)")),
-- 
2.52.0.10.g08704017180

[PATCH v2 3/3] doc: replay: link section using markup

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-replay.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index 1e2469b9034..22fd1b271af 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -19,7 +19,7 @@ the working tree and the index untouched. By default, updates the
 relevant references using an atomic transaction (all refs update or
 none). Use `--ref-action=print` to avoid automatic ref updates and
 instead get update commands that can be piped to `git update-ref --stdin`
-(see the OUTPUT section below).
+(see the <<output,OUTPUT>> section below).
 
 THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
 
@@ -67,6 +67,7 @@ The default mode can be configured via the `replay.refAction` configuration vari
 
 include::rev-list-options.adoc[]
 
+[[output]]
 OUTPUT
 ------
 
-- 
2.52.0.10.g08704017180

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

[Phillip Wood]

On 13/12/2025 13:46, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> Explicitly say that conflicts do not give any output. I found this a bit
> confusing with the current doc since I am used to other commands
> complaining loudly.
> 
> § Changes in v2
> 
> Patch 2/3: improve `--contained` and mention that it requires `--onto`.

The new text looks good, I don't really understand the commit message 
but the intent of the change is clear enough.

Thanks for improving the documentation

Phillip

> Kristoffer Haugsbakk (3):
>    doc: replay: mention no output on conflicts
>    replay: improve --contained and add to doc
>    doc: replay: link section using markup
> 
>   Documentation/git-replay.adoc | 11 ++++++++++-
>   builtin/replay.c              |  2 +-
>   2 files changed, 11 insertions(+), 2 deletions(-)
> 
> Interdiff against v1:
> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
> index 04944a5fa23..22fd1b271af 100644
> --- a/Documentation/git-replay.adoc
> +++ b/Documentation/git-replay.adoc
> @@ -43,7 +43,8 @@ point at the tip of the resulting history. This is different from `--onto`,
>   which uses the target only as a starting point without updating it.
>   
>   --contained::
> -	Advance all branches contained in <revision-range>.
> +	Update all branches that point at commits in
> +	<revision-range>. Requires `--onto`.
>   
>   --ref-action[=<mode>]::
>   	Control how references are updated. The mode can be:
> diff --git a/builtin/replay.c b/builtin/replay.c
> index 6606a2c94bc..9e5ad64cad6 100644
> --- a/builtin/replay.c
> +++ b/builtin/replay.c
> @@ -377,7 +377,7 @@ int cmd_replay(int argc,
>   			   N_("revision"),
>   			   N_("replay onto given commit")),
>   		OPT_BOOL(0, "contained", &contained,
> -			 N_("advance all branches contained in revision-range")),
> +			 N_("update all branches that point at commits in <revision-range>")),
>   		OPT_STRING(0, "ref-action", &ref_action,
>   			   N_("mode"),
>   			   N_("control ref update behavior (update|print)")),
> Range-diff against v1:
> 1:  b9ec24c8b8f = 1:  b9ec24c8b8f doc: replay: mention no output on conflicts
> 2:  02a80ee87b5 ! 2:  27bf2ac7a0b doc: replay: document --contained
>      @@ Metadata
>       Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
>       
>        ## Commit message ##
>      -    doc: replay: document --contained
>      +    replay: improve --contained and add to doc
>       
>      -    Copy the text from `replay_options` in `builtin/replay.c`.
>      +    There is no documentation for `--contained`.
>       
>      +    Start by copying the text from `replay_options` in `builtin/
>      +    replay.c`. But some people think that the existing text is a
>      +    bit unclear; what does it mean for a branch to be contained
>      +    in a revision range? Let’s include the implied commits here:
>      +    the branches that point at commits in the range.
>      +
>      +    Also use “update” instead of “advance”. “Update” is the verb
>      +    commonly used in this context.
>      +
>      +    Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
>      +    Helped-by: Junio C Hamano <gitster@pobox.com>
>           Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
>       
>      +
>      + ## Notes (series) ##
>      +    v2:
>      +
>      +    Don’t just copy `--contained` over. Improve it on both sites after discussing
>      +    with reviewers.
>      +
>      +    Also mention that `--onto` is required.
>      +
>        ## Documentation/git-replay.adoc ##
>       @@ Documentation/git-replay.adoc: The history is replayed on top of the <branch> and <branch> is updated to
>        point at the tip of the resulting history. This is different from `--onto`,
>        which uses the target only as a starting point without updating it.
>        
>       +--contained::
>      -+	Advance all branches contained in <revision-range>.
>      ++	Update all branches that point at commits in
>      ++	<revision-range>. Requires `--onto`.
>       +
>        --ref-action[=<mode>]::
>        	Control how references are updated. The mode can be:
>        +
>      +
>      + ## builtin/replay.c ##
>      +@@ builtin/replay.c: int cmd_replay(int argc,
>      + 			   N_("revision"),
>      + 			   N_("replay onto given commit")),
>      + 		OPT_BOOL(0, "contained", &contained,
>      +-			 N_("advance all branches contained in revision-range")),
>      ++			 N_("update all branches that point at commits in <revision-range>")),
>      + 		OPT_STRING(0, "ref-action", &ref_action,
>      + 			   N_("mode"),
>      + 			   N_("control ref update behavior (update|print)")),
> 3:  ca83b00343d = 3:  4e851fdff34 doc: replay: link section using markup
> 
> base-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06

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

[Kristoffer Haugsbakk]

On Mon, Dec 15, 2025, at 11:13, Phillip Wood wrote:
> On 13/12/2025 13:46, kristofferhaugsbakk@fastmail.com wrote:
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>
>> Explicitly say that conflicts do not give any output. I found this a bit
>> confusing with the current doc since I am used to other commands
>> complaining loudly.
>>
>> § Changes in v2
>>
>> Patch 2/3: improve `--contained` and mention that it requires `--onto`.
>
> The new text looks good, I don't really understand the commit message
> but the intent of the change is clear enough.
>
> Thanks for improving the documentation

Thank you. But I’m not glad that the commit message is not clear. I
would need some guidance on how to write it because it seems clear to
me. Something with my brain state I guess.

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

[Junio C Hamano]

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

> On Mon, Dec 15, 2025, at 11:13, Phillip Wood wrote:
>> On 13/12/2025 13:46, kristofferhaugsbakk@fastmail.com wrote:
>>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>>
>>> Explicitly say that conflicts do not give any output. I found this a bit
>>> confusing with the current doc since I am used to other commands
>>> complaining loudly.
>>>
>>> § Changes in v2
>>>
>>> Patch 2/3: improve `--contained` and mention that it requires `--onto`.
>>
>> The new text looks good, I don't really understand the commit message
>> but the intent of the change is clear enough.
>>
>> Thanks for improving the documentation
>
> Thank you. But I’m not glad that the commit message is not clear. I
> would need some guidance on how to write it because it seems clear to
> me. Something with my brain state I guess.

They are already in 'next', but let's see if there are pain points.

commit 8467c95419acaa826a6c1ca0db0f36a3fd614ae4
Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
Date:   Sat Dec 13 14:46:56 2025 +0100

    doc: replay: mention no output on conflicts
    
    Some commands will produce output on stderr if there are conflicts, but
    git-replay(1) is completely silent. Explicitly spell that out.
    
    Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

Looks clear enough to me.


commit 03d7c9c457ba68f28269dcd607b9026ea6c6c9c8
Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
Date:   Sat Dec 13 14:46:57 2025 +0100

    replay: improve --contained and add to doc
    
    There is no documentation for `--contained`.
    
    Start by copying the text from `replay_options` in `builtin/
    replay.c`. But some people think that the existing text is a
    bit unclear; what does it mean for a branch to be contained
    in a revision range? Let’s include the implied commits here:
    the branches that point at commits in the range.
    
    Also use “update” instead of “advance”. “Update” is the verb
    commonly used in this context.
    
    Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
    Helped-by: Junio C Hamano <gitster@pobox.com>
    Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

As to the title, "improve --contained" hinted me there is some code
changes for behaviour, but there isn't, so that part may have been a
bit misleading.  "improve short-help of --contained and add to doc",
perhaps.

I think the problem people found in the second paragraph is because
it is so unclear what it is talking about if you read it without
looking at the patch text.  You started from the existing "advance
all branches contained in revision-range", taken from the existing
short-help in replay_options[].  But without seeing that "branches
contained" text, it is natural that readers find it hard to judge
the validity of "But some people think that..." claim themselves.

If I were writing this (but I will not rewind 'next' to do so),
I'd say something like:

    replay: improve the help of the `--contained` option and document it

    "git replay -h" explains "--contained" as

	advance all branches contained in revision-range

    but it may be unclear when exactly a branch is contained in a
    revision range.  Because the command updates a branch that
    points at a commit that gets rewritten to point at the result of
    the rewrite, "update branches that point at commits in the
    range" says what we want to say more clearly and concisely.

    The "--contained" option has no description in "git replay"
    documentation.  Use the improved phrase there, too.

probably.  In any case, it is a good exercise to see if the proposed
log message can be easily understood without looking at the code
change.


commit 9ba08b30a117e6925a9e5e87c92b37de7396d3a4
Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
Date:   Sat Dec 13 14:46:58 2025 +0100

    doc: replay: link section using markup
    
    Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

Looking good.

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

[Phillip Wood]

On 16/12/2025 00:29, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>>
>> Thank you. But I’m not glad that the commit message is not clear. I
>> would need some guidance on how to write it because it seems clear to
>> me. Something with my brain state I guess.
> 
> commit 03d7c9c457ba68f28269dcd607b9026ea6c6c9c8
> Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
> Date:   Sat Dec 13 14:46:57 2025 +0100
> 
>      replay: improve --contained and add to doc
>      
>      There is no documentation for `--contained`.
>      
>      Start by copying the text from `replay_options` in `builtin/
>      replay.c`. But some people think that the existing text is a
>      bit unclear; what does it mean for a branch to be contained
>      in a revision range? Let’s include the implied commits here:
>      the branches that point at commits in the range.
>      
>      Also use “update” instead of “advance”. “Update” is the verb
>      commonly used in this context.
>      
>      Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
>      Helped-by: Junio C Hamano <gitster@pobox.com>
>      Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
>      Signed-off-by: Junio C Hamano <gitster@pobox.com>
> 
> As to the title, "improve --contained" hinted me there is some code
> changes for behaviour, but there isn't, so that part may have been a
> bit misleading.  "improve short-help of --contained and add to doc",
> perhaps.
> 
> I think the problem people found in the second paragraph is because
> it is so unclear what it is talking about if you read it without
> looking at the patch text.  You started from the existing "advance
> all branches contained in revision-range", taken from the existing
> short-help in replay_options[].  But without seeing that "branches
> contained" text, it is natural that readers find it hard to judge
> the validity of "But some people think that..." claim themselves.

That's a good summary of what I found confusing. I like you suggested 
message below but I agree it is not worth messing with it now it is in next.

Thanks

Phillip

> If I were writing this (but I will not rewind 'next' to do so),
> I'd say something like:
> 
>      replay: improve the help of the `--contained` option and document it
> 
>      "git replay -h" explains "--contained" as
> 
> 	advance all branches contained in revision-range
> 
>      but it may be unclear when exactly a branch is contained in a
>      revision range.  Because the command updates a branch that
>      points at a commit that gets rewritten to point at the result of
>      the rewrite, "update branches that point at commits in the
>      range" says what we want to say more clearly and concisely.
> 
>      The "--contained" option has no description in "git replay"
>      documentation.  Use the improved phrase there, too.
> 
> probably.  In any case, it is a good exercise to see if the proposed
> log message can be easily understood without looking at the code
> change.
> 
> 
> commit 9ba08b30a117e6925a9e5e87c92b37de7396d3a4
> Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
> Date:   Sat Dec 13 14:46:58 2025 +0100
> 
>      doc: replay: link section using markup
>      
>      Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
>      Signed-off-by: Junio C Hamano <gitster@pobox.com>
> 
> Looking good.

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

[Kristoffer Haugsbakk]

On Tue, Dec 16, 2025, at 01:29, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>>[snip]
>> Thank you. But I’m not glad that the commit message is not clear. I
>> would need some guidance on how to write it because it seems clear to
>> me. Something with my brain state I guess.
>
> They are already in 'next', but let's see if there are pain points.
>
>[snip]
> commit 03d7c9c457ba68f28269dcd607b9026ea6c6c9c8
> Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
> Date:   Sat Dec 13 14:46:57 2025 +0100
>
>     replay: improve --contained and add to doc
>
>     There is no documentation for `--contained`.
>
>     Start by copying the text from `replay_options` in `builtin/
>     replay.c`. But some people think that the existing text is a
>     bit unclear; what does it mean for a branch to be contained
>     in a revision range? Let’s include the implied commits here:
>     the branches that point at commits in the range.
>
>     Also use “update” instead of “advance”. “Update” is the verb
>     commonly used in this context.
>
>     Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
>     Helped-by: Junio C Hamano <gitster@pobox.com>
>     Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
>     Signed-off-by: Junio C Hamano <gitster@pobox.com>
>
> As to the title, "improve --contained" hinted me there is some code
> changes for behaviour, but there isn't, so that part may have been a
> bit misleading.  "improve short-help of --contained and add to doc",
> perhaps.

Oh right, of course. The original area was `doc` and in that case this
would have been fine. But I didn’t consider the `replay` area. So now it
looks like the `--contained` option logic has been changed.

>
> I think the problem people found in the second paragraph is because
> it is so unclear what it is talking about if you read it without
> looking at the patch text.  You started from the existing "advance
> all branches contained in revision-range", taken from the existing
> short-help in replay_options[].  But without seeing that "branches
> contained" text, it is natural that readers find it hard to judge
> the validity of "But some people think that..." claim themselves.
>
> If I were writing this (but I will not rewind 'next' to do so),
> I'd say something like:
>
>     replay: improve the help of the `--contained` option and document it
>
>     "git replay -h" explains "--contained" as
>
> 	advance all branches contained in revision-range
>
>     but it may be unclear when exactly a branch is contained in a
>     revision range.  Because the command updates a branch that
>     points at a commit that gets rewritten to point at the result of
>     the rewrite, "update branches that point at commits in the
>     range" says what we want to say more clearly and concisely.
>
>     The "--contained" option has no description in "git replay"
>     documentation.  Use the improved phrase there, too.
>
> probably.  In any case, it is a good exercise to see if the proposed
> log message can be easily understood without looking at the code
> change.

Okay, now I get it. It turns out I’m still learning how to write commit
messages with the right amount of context.

And thanks to Phillip for confirming.

>[snip]