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

From: [email-masked]
Date: Sat, 13 Dec 2025 14:46:57 +0100

From: Kristoffer Haugsbakk <[email-masked]>

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 <[email-masked]>
Helped-by: Junio C Hamano <[email-masked]>
Signed-off-by: Kristoffer Haugsbakk <[email-masked]>
---

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