From: Phillip Wood <phillip.wood123@gmail.com>
Date: Mon, 15 Dec 2025 10:13:16 GMT
Subject: Re: [PATCH v2 0/3] doc: replay: improvements like "mention no output on conflicts"
Message-ID: <8fa21ce8-1e02-419f-b82a-0e4a41f7e2d8@gmail.com>
In-Reply-To: <V2_CV_replay_conflict.12f@msgid.xyz>

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