@@ -9,15 +9,16 @@ git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos t
99SYNOPSIS
1010--------
1111[verse]
12- (EXPERIMENTAL!) 'git replay' ([-- contained] -- onto <newbase > | -- advance <branch >) <revision-range >...
12+ (EXPERIMENTAL!) 'git replay' ([-- contained] -- onto <newbase > | -- advance <branch >) [ -- ref-action[=< mode >]] <revision-range >...
1313
1414DESCRIPTION
1515-----------
1616
1717Takes ranges of commits and replays them onto a new location. Leaves
18- the working tree and the index untouched, and updates no references.
19- The output of this command is meant to be used as input to
20- `git update-ref --stdin` , which would update the relevant branches
18+ the working tree and the index untouched. By default, updates the
19+ relevant references using an atomic transaction (all refs update or
20+ none). Use `--ref-action=print` to avoid automatic ref updates and
21+ instead get update commands that can be piped to `git update-ref --stdin`
2122(see the OUTPUT section below).
2223
2324THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
@@ -29,18 +30,29 @@ OPTIONS
2930 Starting point at which to create the new commits. May be any
3031 valid commit, and not just an existing branch name.
3132+
32- When `--onto` is specified, the update-ref command(s) in the output will
33- update the branch(es) in the revision range to point at the new
34- commits, similar to the way how `git rebase --update-refs` updates
35- multiple branches in the affected range.
33+ When `--onto` is specified, the branch(es) in the revision range will be
34+ updated to point at the new commits, similar to the way `git rebase --update-refs`
35+ updates multiple branches in the affected range.
3636
3737-- advance <branch >::
3838 Starting point at which to create the new commits; must be a
3939 branch name.
4040+
41- When `--advance` is specified, the update-ref command(s) in the output
42- will update the branch passed as an argument to `--advance` to point at
43- the new commits (in other words, this mimics a cherry-pick operation).
41+ The history is replayed on top of the <branch > and <branch > is updated to
42+ point at the tip of the resulting history. This is different from `--onto` ,
43+ which uses the target only as a starting point without updating it.
44+
45+ -- ref-action[=<mode >]::
46+ Control how references are updated. The mode can be:
47+ +
48+ --
49+ * `update` (default): Update refs directly using an atomic transaction.
50+ All refs are updated or none are (all-or-nothing behavior).
51+ * `print` : Output update-ref commands for pipeline use. This is the
52+ traditional behavior where output can be piped to `git update-ref --stdin` .
53+ --
54+ +
55+ The default mode can be configured via the `replay.refAction` configuration variable.
4456
4557<revision-range >::
4658 Range of commits to replay. More than one <revision-range > can
@@ -54,8 +66,11 @@ include::rev-list-options.adoc[]
5466OUTPUT
5567------
5668
57- When there are no conflicts, the output of this command is usable as
58- input to `git update-ref --stdin` . It is of the form:
69+ By default, or with `--ref-action=update` , this command produces no output on
70+ success, as refs are updated directly using an atomic transaction.
71+
72+ When using `--ref-action=print` , the output is usable as input to
73+ `git update-ref --stdin` . It is of the form:
5974
6075 update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
6176 update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
@@ -81,40 +96,44 @@ To simply rebase `mybranch` onto `target`:
8196
8297------------
8398$ git replay --onto target origin/main..mybranch
99+ ------------
100+
101+ The refs are updated atomically and no output is produced on success.
102+
103+ To see what would be updated without actually updating:
104+
105+ ------------
106+ $ git replay --ref-action=print --onto target origin/main..mybranch
84107update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH}
85108------------
86109
87110To cherry-pick the commits from mybranch onto target:
88111
89112------------
90113$ git replay --advance target origin/main..mybranch
91- update refs/heads/target ${NEW_target_HASH} ${OLD_target_HASH}
92114------------
93115
94116Note that the first two examples replay the exact same commits and on
95117top of the exact same new base, they only differ in that the first
96- provides instructions to make mybranch point at the new commits and
97- the second provides instructions to make target point at them.
118+ updates mybranch to point at the new commits and the second updates
119+ target to point at them.
98120
99121What if you have a stack of branches, one depending upon another, and
100122you'd really like to rebase the whole set?
101123
102124------------
103125$ git replay --contained --onto origin/main origin/main..tipbranch
104- update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
105- update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
106- update refs/heads/tipbranch ${NEW_tipbranch_HASH} ${OLD_tipbranch_HASH}
107126------------
108127
128+ All three branches (`branch1`, `branch2`, and `tipbranch`) are updated
129+ atomically.
130+
109131When calling `git replay`, one does not need to specify a range of
110132commits to replay using the syntax `A..B`; any range expression will
111133do:
112134
113135------------
114136$ git replay --onto origin/main ^base branch1 branch2 branch3
115- update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
116- update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
117- update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}
118137------------
119138
120139This will simultaneously rebase `branch1`, `branch2`, and `branch3`,
0 commit comments