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

[kristofferhaugsbakk@fastmail.com]

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