patch, 3 partsdoc: replay: improvements like "mention no output on conflicts"

> 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

> 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

> 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

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

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

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

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

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