git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v3 2/3] replay: use stuck form in documentation and help message

From
Toon Claes <toon@iotcl.com>
Date
Apr 1, 2026, 20:55 UTC
Message-ID
<20260401-toon-replay-arbitrary-ref-v3-2-a0b4fabb34b3@iotcl.com>
In-Reply-To
<20260401-toon-replay-arbitrary-ref-v3-0-a0b4fabb34b3@iotcl.com>

gitcli(7) suggests to use stuck form. Change the documentation strings to use this form.

While at it, reorder them to match the order in the docs.
Signed-off-by: Toon Claes <toon@iotcl.com>
---
 Documentation/git-replay.adoc | 25 +++++++++++++------------
 builtin/replay.c              |  4 ++--
 2 files changed, 15 insertions(+), 14 deletions(-)
diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc
index 997097e420..5bb478c281 100644
--- a/Documentation/git-replay.adoc
+++ b/Documentation/git-replay.adoc
@@ -9,7 +9,8 @@ git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos t
 SYNOPSIS
 --------
 [verse]
-(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch> | --revert <branch>) [--ref-action[=<mode>]] <revision-range>
+(EXPERIMENTAL!) 'git replay' ([--contained] --onto=<newbase> | --advance=<branch> | --revert=<branch>)
+			     [--ref-action=<mode>] <revision-range>
 
 DESCRIPTION
 -----------
@@ -26,7 +27,7 @@ THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
 OPTIONS
 -------
 
---onto <newbase>::
+--onto=<newbase>::
 	Starting point at which to create the new commits.  May be any
 	valid commit, and not just an existing branch name.
 +
@@ -34,7 +35,7 @@ When `--onto` is specified, the branch(es) in the revision range will be
 updated to point at the new commits, similar to the way `git rebase --update-refs`
 updates multiple branches in the affected range.
 
---advance <branch>::
+--advance=<branch>::
 	Starting point at which to create the new commits; must be a
 	branch name.
 +
@@ -42,7 +43,7 @@ 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.
 
---revert <branch>::
+--revert=<branch>::
 	Starting point at which to create the reverted commits; must be a
 	branch name.
 +
@@ -79,8 +80,8 @@ The default mode can be configured via the `replay.refAction` configuration vari
 
 <revision-range>::
 	Range of commits to replay; see "Specifying Ranges" in
-	linkgit:git-rev-parse[1]. In `--advance <branch>` or
-	`--revert <branch>` mode, the range should have a single tip,
+	linkgit:git-rev-parse[1]. In `--advance=<branch>` or
+	`--revert=<branch>` mode, the range should have a single tip,
 	so that it's clear to which tip the advanced or reverted
 	<branch> should point. Any commits in the range whose changes
 	are already present in the branch the commits are being
@@ -127,7 +128,7 @@ EXAMPLES
 To simply rebase `mybranch` onto `target`:
 
 ------------
-$ git replay --onto target origin/main..mybranch
+$ git replay --onto=target origin/main..mybranch
 ------------
 
 The refs are updated atomically and no output is produced on success.
@@ -135,14 +136,14 @@ The refs are updated atomically and no output is produced on success.
 To see what would be updated without actually updating:
 
 ------------
-$ git replay --ref-action=print --onto target origin/main..mybranch
+$ git replay --ref-action=print --onto=target origin/main..mybranch
 update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH}
 ------------
 
 To cherry-pick the commits from mybranch onto target:
 
 ------------
-$ git replay --advance target origin/main..mybranch
+$ git replay --advance=target origin/main..mybranch
 ------------
 
 Note that the first two examples replay the exact same commits and on
@@ -154,7 +155,7 @@ What if you have a stack of branches, one depending upon another, and
 you'd really like to rebase the whole set?
 
 ------------
-$ git replay --contained --onto origin/main origin/main..tipbranch
+$ git replay --contained --onto=origin/main origin/main..tipbranch
 ------------
 
 All three branches (`branch1`, `branch2`, and `tipbranch`) are updated
@@ -165,7 +166,7 @@ commits to replay using the syntax `A..B`; any range expression will
 do:
 
 ------------
-$ git replay --onto origin/main ^base branch1 branch2 branch3
+$ git replay --onto=origin/main ^base branch1 branch2 branch3
 ------------
 
 This will simultaneously rebase `branch1`, `branch2`, and `branch3`,
@@ -176,7 +177,7 @@ that they have in common, but that does not need to be the case.
 To revert commits on a branch:
 
 ------------
-$ git replay --revert main topic~2..topic
+$ git replay --revert=main topic~2..topic
 ------------
 
 This reverts the last two commits from `topic`, creating revert commits on
diff --git a/builtin/replay.c b/builtin/replay.c
index 85aa9fa0a4..fbfeb780b6 100644
--- a/builtin/replay.c
+++ b/builtin/replay.c
@@ -84,8 +84,8 @@ int cmd_replay(int argc,
 
 	const char *const replay_usage[] = {
 		N_("(EXPERIMENTAL!) git replay "
-		   "([--contained] --onto <newbase> | --advance <branch> | --revert <branch>) "
-		   "[--ref-action[=<mode>]] <revision-range>"),
+		   "([--contained] --onto=<newbase> | --advance=<branch> | --revert=<branch>)\n"
+		   "[--ref-action=<mode>] <revision-range>"),
 		NULL
 	};
 	struct option replay_options[] = {
-- 
2.53.0.310.g728cabbaf7
Previous: Toon ClaesNext: Toon Claes
Message 24 of 25 in “Add option --ref to git-replay(1)”
  1. 0/3 Add option --ref to git-replay(1)Toon Claes, Mar 23, 2026
  2. 1/3 t3650: use option with value consistenly with equal signToon Claes, Mar 23, 2026
  3. Kristoffer HaugsbakkMar 23, 2026
  4. Junio C HamanoMar 23, 2026
  5. Toon ClaesMar 25, 2026
  6. 2/3 builtin/replay: improve documentation on optionsToon Claes, Mar 23, 2026
  7. 3/3 replay: allow to specify a ref with option --refToon Claes, Mar 23, 2026
  8. Tian YuchenMar 23, 2026
  9. Toon ClaesMar 25, 2026
  10. Kristoffer HaugsbakkMar 23, 2026
  11. Toon ClaesMar 25, 2026
  12. 0/3 Add option --ref to git-replay(1)Toon Claes, Mar 25, 2026
  13. 1/3 builtin/replay: mark options as not negatableToon Claes, Mar 25, 2026
  14. 2/3 replay: use stuck form in documentation and help messageToon Claes, Mar 25, 2026
  15. 3/3 replay: allow to specify a ref with option --refToon Claes, Mar 25, 2026
  16. Junio C HamanoMar 25, 2026
  17. Toon ClaesMar 31, 2026
  18. Junio C HamanoMar 25, 2026
  19. Junio C HamanoMar 26, 2026
  20. Toon ClaesMar 31, 2026
  21. Junio C HamanoMar 31, 2026
  22. 0/3 Add option --ref to git-replay(1)Toon Claes, Apr 1, 2026
  23. 1/3 builtin/replay: mark options as not negatableToon Claes, Apr 1, 2026
  24. 2/3 replay: use stuck form in documentation and help messageToon Claes, Apr 1, 2026
  25. 3/3 replay: allow to specify a ref with option --refToon Claes, Apr 1, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.