replay: make atomic ref updates the default behavior
The git replay command currently outputs update commands that can be piped to update-ref to achieve a rebase, e.g. git replay --onto main topic1..topic2 | git update-ref --stdin This separation had advantages for three special cases: * it made testing easy (when state isn't modified from one step to the next, you don't need to make temporary branches or have undo commands, or try to track the changes) * it provided a natural can-it-rebase-cleanly (and what would it rebase to) capability without automatically updating refs, similar to a --dry-run * it provided a natural low-level tool for the suite of hash-object, mktree, commit-tree, mktag, merge-tree, and update-ref, allowing users to have another building block for experimentation and making new tools However, it should be noted that all three of these are somewhat special cases; users, whether on the client or server side, would almost certainly find it more ergonomic to simply have the updating of refs be the default. For server-side operations in particular, the pipeline architecture creates process coordination overhead. Server implementations that need to perform rebases atomically must maintain additional code to: 1. Spawn and manage a pipeline between git-replay and git-update-ref 2. Coordinate stdout/stderr streams across the pipe boundary 3. Handle partial failure states if the pipeline breaks mid-execution 4. Parse and validate the update-ref command output Change the default behavior to update refs directly, and atomically (at least to the extent supported by the refs backend in use). This eliminates the process coordination overhead for the common case. For users needing the traditional pipeline workflow, add a new --ref-action=<mode> option that preserves the original behavior: git replay --ref-action=print --onto main topic1..topic2 | git update-ref --stdin The mode can be: * update (default): Update refs directly using an atomic transaction * print: Output update-ref commands for pipeline use Test suite changes: All existing tests that expected command output now use --ref-action=print to preserve their original behavior. This keeps the tests valid while allowing them to verify that the pipeline workflow still works correctly. New tests were added to verify: - Default atomic behavior (no output, refs updated directly) - Bare repository support (server-side use case) - Equivalence between traditional pipeline and atomic updates - Real atomicity using a lock file to verify all-or-nothing guarantee - Test isolation using test_when_finished to clean up state - Reflog messages include replay mode and target A following commit will add a replay.refAction configuration option for users who prefer the traditional pipeline output as their default behavior. Helped-by: Elijah Newren <newren@gmail.com> Helped-by: Patrick Steinhardt <ps@pks.im> Helped-by: Christian Couder <christian.couder@gmail.com> Helped-by: Phillip Wood <phillip.wood123@gmail.com> Signed-off-by: Siddharth Asthana <siddharthasthana31@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Siddharth Asthana committed
Nov 6, 2025 at 00:46 UTC
15cd4ef1f495e51f7db39583b7f562e7170da3d2
3 files changed
+199
-40
Documentation/git-replay.adoc
+39
-22
@@ -9,15 +9,16 @@ git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos t
9
SYNOPSIS
10
--------
11
[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>...
13
14
DESCRIPTION
15
-----------
16
17
Takes 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`
22
(see the OUTPUT section below).
23
24
THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
@@ -29,18 +30,27 @@ OPTIONS
30
Starting point at which to create the new commits. May be any
31
valid commit, and not just an existing branch name.
32
+
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.
36
37
--advance <branch>::
38
Starting point at which to create the new commits; must be a
39
branch name.
40
+
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
<revision-range>::
56
Range of commits to replay. More than one <revision-range> can
@@ -54,8 +64,11 @@ include::rev-list-options.adoc[]
64
OUTPUT
65
------
66
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:
67
+By default, or with `--ref-action=update`, this command produces no output on
68
+success, as refs are updated directly using an atomic transaction.
69
+
70
+When using `--ref-action=print`, the output is usable as input to
71
+`git update-ref --stdin`. It is of the form:
72
73
update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
74
update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
@@ -81,6 +94,14 @@ To simply rebase `mybranch` onto `target`:
94
95
------------
96
$ git replay --onto target origin/main..mybranch
97
+------------
98
+
99
+The refs are updated atomically and no output is produced on success.
100
+
101
+To see what would be updated without actually updating:
102
+
103
+------------
104
+$ git replay --ref-action=print --onto target origin/main..mybranch
105
update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH}
106
------------
107
@@ -88,33 +109,29 @@ To cherry-pick the commits from mybranch onto target:
109
110
------------
111
$ git replay --advance target origin/main..mybranch
91
-update refs/heads/target ${NEW_target_HASH} ${OLD_target_HASH}
112
------------
113
114
Note that the first two examples replay the exact same commits and on
115
top 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.
116
+updates mybranch to point at the new commits and the second updates
117
+target to point at them.
118
119
What if you have a stack of branches, one depending upon another, and
120
you'd really like to rebase the whole set?
121
122
------------
123
$ 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}
124
------------
125
126
+All three branches (`branch1`, `branch2`, and `tipbranch`) are updated
127
+atomically.
128
+
129
When calling `git replay`, one does not need to specify a range of
130
commits to replay using the syntax `A..B`; any range expression will
131
do:
132
133
------------
134
$ 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}
135
------------
136
137
This will simultaneously rebase `branch1`, `branch2`, and `branch3`,
builtin/replay.c
+101
-10
@@ -20,6 +20,11 @@
20
#include <oidset.h>
21
#include <tree.h>
22
23
+enum ref_action_mode {
24
+ REF_ACTION_UPDATE,
25
+ REF_ACTION_PRINT,
26
+};
27
+
28
static const char *short_commit_name(struct repository *repo,
29
struct commit *commit)
30
{
@@ -284,6 +289,38 @@ static struct commit *pick_regular_commit(struct repository *repo,
289
return create_commit(repo, result->tree, pickme, replayed_base);
290
}
291
292
+static enum ref_action_mode parse_ref_action_mode(const char *ref_action, const char *source)
293
+{
294
+ if (!ref_action || !strcmp(ref_action, "update"))
295
+ return REF_ACTION_UPDATE;
296
+ if (!strcmp(ref_action, "print"))
297
+ return REF_ACTION_PRINT;
298
+ die(_("invalid %s value: '%s'"), source, ref_action);
299
+}
300
+
301
+static int handle_ref_update(enum ref_action_mode mode,
302
+ struct ref_transaction *transaction,
303
+ const char *refname,
304
+ const struct object_id *new_oid,
305
+ const struct object_id *old_oid,
306
+ const char *reflog_msg,
307
+ struct strbuf *err)
308
+{
309
+ switch (mode) {
310
+ case REF_ACTION_PRINT:
311
+ printf("update %s %s %s\n",
312
+ refname,
313
+ oid_to_hex(new_oid),
314
+ oid_to_hex(old_oid));
315
+ return 0;
316
+ case REF_ACTION_UPDATE:
317
+ return ref_transaction_update(transaction, refname, new_oid, old_oid,
318
+ NULL, NULL, 0, reflog_msg, err);
319
+ default:
320
+ BUG("unknown ref_action_mode %d", mode);
321
+ }
322
+}
323
+
324
int cmd_replay(int argc,
325
const char **argv,
326
const char *prefix,
@@ -294,6 +331,8 @@ int cmd_replay(int argc,
331
struct commit *onto = NULL;
332
const char *onto_name = NULL;
333
int contained = 0;
334
+ const char *ref_action = NULL;
335
+ enum ref_action_mode ref_mode = REF_ACTION_UPDATE;
336
337
struct rev_info revs;
338
struct commit *last_commit = NULL;
@@ -302,12 +341,15 @@ int cmd_replay(int argc,
341
struct merge_result result;
342
struct strset *update_refs = NULL;
343
kh_oid_map_t *replayed_commits;
344
+ struct ref_transaction *transaction = NULL;
345
+ struct strbuf transaction_err = STRBUF_INIT;
346
+ struct strbuf reflog_msg = STRBUF_INIT;
347
int ret = 0;
348
307
- const char * const replay_usage[] = {
349
+ const char *const replay_usage[] = {
350
N_("(EXPERIMENTAL!) git replay "
351
"([--contained] --onto <newbase> | --advance <branch>) "
310
- "<revision-range>..."),
352
+ "[--ref-action[=<mode>]] <revision-range>..."),
353
NULL
354
};
355
struct option replay_options[] = {
@@ -319,6 +361,9 @@ int cmd_replay(int argc,
361
N_("replay onto given commit")),
362
OPT_BOOL(0, "contained", &contained,
363
N_("advance all branches contained in revision-range")),
364
+ OPT_STRING(0, "ref-action", &ref_action,
365
+ N_("mode"),
366
+ N_("control ref update behavior (update|print)")),
367
OPT_END()
368
};
369
@@ -333,6 +378,10 @@ int cmd_replay(int argc,
378
die_for_incompatible_opt2(!!advance_name_opt, "--advance",
379
contained, "--contained");
380
381
+ /* Parse ref action mode */
382
+ if (ref_action)
383
+ ref_mode = parse_ref_action_mode(ref_action, "--ref-action");
384
+
385
advance_name = xstrdup_or_null(advance_name_opt);
386
387
repo_init_revisions(repo, &revs, prefix);
@@ -389,6 +438,24 @@ int cmd_replay(int argc,
438
determine_replay_mode(repo, &revs.cmdline, onto_name, &advance_name,
439
&onto, &update_refs);
440
441
+ /* Build reflog message */
442
+ if (advance_name_opt)
443
+ strbuf_addf(&reflog_msg, "replay --advance %s", advance_name_opt);
444
+ else
445
+ strbuf_addf(&reflog_msg, "replay --onto %s",
446
+ oid_to_hex(&onto->object.oid));
447
+
448
+ /* Initialize ref transaction if using update mode */
449
+ if (ref_mode == REF_ACTION_UPDATE) {
450
+ transaction = ref_store_transaction_begin(get_main_ref_store(repo),
451
+ 0, &transaction_err);
452
+ if (!transaction) {
453
+ ret = error(_("failed to begin ref transaction: %s"),
454
+ transaction_err.buf);
455
+ goto cleanup;
456
+ }
457
+ }
458
+
459
if (!onto) /* FIXME: Should handle replaying down to root commit */
460
die("Replaying down to root commit is not supported yet!");
461
@@ -434,10 +501,16 @@ int cmd_replay(int argc,
501
if (decoration->type == DECORATION_REF_LOCAL &&
502
(contained || strset_contains(update_refs,
503
decoration->name))) {
437
- printf("update %s %s %s\n",
438
- decoration->name,
439
- oid_to_hex(&last_commit->object.oid),
440
- oid_to_hex(&commit->object.oid));
504
+ if (handle_ref_update(ref_mode, transaction,
505
+ decoration->name,
506
+ &last_commit->object.oid,
507
+ &commit->object.oid,
508
+ reflog_msg.buf,
509
+ &transaction_err) < 0) {
510
+ ret = error(_("failed to update ref '%s': %s"),
511
+ decoration->name, transaction_err.buf);
512
+ goto cleanup;
513
+ }
514
}
515
decoration = decoration->next;
516
}
@@ -445,10 +518,24 @@ int cmd_replay(int argc,
518
519
/* In --advance mode, advance the target ref */
520
if (result.clean == 1 && advance_name) {
448
- printf("update %s %s %s\n",
449
- advance_name,
450
- oid_to_hex(&last_commit->object.oid),
451
- oid_to_hex(&onto->object.oid));
521
+ if (handle_ref_update(ref_mode, transaction, advance_name,
522
+ &last_commit->object.oid,
523
+ &onto->object.oid,
524
+ reflog_msg.buf,
525
+ &transaction_err) < 0) {
526
+ ret = error(_("failed to update ref '%s': %s"),
527
+ advance_name, transaction_err.buf);
528
+ goto cleanup;
529
+ }
530
+ }
531
+
532
+ /* Commit the ref transaction if we have one */
533
+ if (transaction && result.clean == 1) {
534
+ if (ref_transaction_commit(transaction, &transaction_err)) {
535
+ ret = error(_("failed to commit ref transaction: %s"),
536
+ transaction_err.buf);
537
+ goto cleanup;
538
+ }
539
}
540
541
merge_finalize(&merge_opt, &result);
@@ -460,6 +547,10 @@ int cmd_replay(int argc,
547
ret = result.clean;
548
549
cleanup:
550
+ if (transaction)
551
+ ref_transaction_free(transaction);
552
+ strbuf_release(&transaction_err);
553
+ strbuf_release(&reflog_msg);
554
release_revisions(&revs);
555
free(advance_name);
556
t/t3650-replay-basics.sh
+59
-8
@@ -52,7 +52,7 @@ test_expect_success 'setup bare' '
52
'
53
54
test_expect_success 'using replay to rebase two branches, one on top of other' '
55
- git replay --onto main topic1..topic2 >result &&
55
+ git replay --ref-action=print --onto main topic1..topic2 >result &&
56
57
test_line_count = 1 result &&
58
@@ -68,7 +68,7 @@ test_expect_success 'using replay to rebase two branches, one on top of other' '
68
'
69
70
test_expect_success 'using replay on bare repo to rebase two branches, one on top of other' '
71
- git -C bare replay --onto main topic1..topic2 >result-bare &&
71
+ git -C bare replay --ref-action=print --onto main topic1..topic2 >result-bare &&
72
test_cmp expect result-bare
73
'
74
@@ -86,7 +86,7 @@ test_expect_success 'using replay to perform basic cherry-pick' '
86
# 2nd field of result is refs/heads/main vs. refs/heads/topic2
87
# 4th field of result is hash for main instead of hash for topic2
88
89
- git replay --advance main topic1..topic2 >result &&
89
+ git replay --ref-action=print --advance main topic1..topic2 >result &&
90
91
test_line_count = 1 result &&
92
@@ -102,7 +102,7 @@ test_expect_success 'using replay to perform basic cherry-pick' '
102
'
103
104
test_expect_success 'using replay on bare repo to perform basic cherry-pick' '
105
- git -C bare replay --advance main topic1..topic2 >result-bare &&
105
+ git -C bare replay --ref-action=print --advance main topic1..topic2 >result-bare &&
106
test_cmp expect result-bare
107
'
108
@@ -115,7 +115,7 @@ test_expect_success 'replay fails when both --advance and --onto are omitted' '
115
'
116
117
test_expect_success 'using replay to also rebase a contained branch' '
118
- git replay --contained --onto main main..topic3 >result &&
118
+ git replay --ref-action=print --contained --onto main main..topic3 >result &&
119
120
test_line_count = 2 result &&
121
cut -f 3 -d " " result >new-branch-tips &&
@@ -139,12 +139,12 @@ test_expect_success 'using replay to also rebase a contained branch' '
139
'
140
141
test_expect_success 'using replay on bare repo to also rebase a contained branch' '
142
- git -C bare replay --contained --onto main main..topic3 >result-bare &&
142
+ git -C bare replay --ref-action=print --contained --onto main main..topic3 >result-bare &&
143
test_cmp expect result-bare
144
'
145
146
test_expect_success 'using replay to rebase multiple divergent branches' '
147
- git replay --onto main ^topic1 topic2 topic4 >result &&
147
+ git replay --ref-action=print --onto main ^topic1 topic2 topic4 >result &&
148
149
test_line_count = 2 result &&
150
cut -f 3 -d " " result >new-branch-tips &&
@@ -168,7 +168,7 @@ test_expect_success 'using replay to rebase multiple divergent branches' '
168
'
169
170
test_expect_success 'using replay on bare repo to rebase multiple divergent branches, including contained ones' '
171
- git -C bare replay --contained --onto main ^main topic2 topic3 topic4 >result &&
171
+ git -C bare replay --ref-action=print --contained --onto main ^main topic2 topic3 topic4 >result &&
172
173
test_line_count = 4 result &&
174
cut -f 3 -d " " result >new-branch-tips &&
@@ -217,4 +217,55 @@ test_expect_success 'merge.directoryRenames=false' '
217
--onto rename-onto rename-onto..rename-from
218
'
219
220
+test_expect_success 'default atomic behavior updates refs directly' '
221
+ # Use a separate branch to avoid contaminating topic2 for later tests
222
+ git branch test-atomic topic2 &&
223
+ test_when_finished "git branch -D test-atomic" &&
224
+
225
+ # Test default atomic behavior (no output, refs updated)
226
+ git replay --onto main topic1..test-atomic >output &&
227
+ test_must_be_empty output &&
228
+
229
+ # Verify ref was updated
230
+ git log --format=%s test-atomic >actual &&
231
+ test_write_lines E D M L B A >expect &&
232
+ test_cmp expect actual &&
233
+
234
+ # Verify reflog message includes SHA of onto commit
235
+ git reflog test-atomic -1 --format=%gs >reflog-msg &&
236
+ ONTO_SHA=$(git rev-parse main) &&
237
+ echo "replay --onto $ONTO_SHA" >expect-reflog &&
238
+ test_cmp expect-reflog reflog-msg
239
+'
240
+
241
+test_expect_success 'atomic behavior in bare repository' '
242
+ # Store original state for cleanup
243
+ START=$(git -C bare rev-parse topic2) &&
244
+ test_when_finished "git -C bare update-ref refs/heads/topic2 $START" &&
245
+
246
+ # Test atomic updates work in bare repo
247
+ git -C bare replay --onto main topic1..topic2 >output &&
248
+ test_must_be_empty output &&
249
+
250
+ # Verify ref was updated in bare repo
251
+ git -C bare log --format=%s topic2 >actual &&
252
+ test_write_lines E D M L B A >expect &&
253
+ test_cmp expect actual
254
+'
255
+
256
+test_expect_success 'reflog message for --advance mode' '
257
+ # Store original state
258
+ START=$(git rev-parse main) &&
259
+ test_when_finished "git update-ref refs/heads/main $START" &&
260
+
261
+ # Test --advance mode reflog message
262
+ git replay --advance main topic1..topic2 >output &&
263
+ test_must_be_empty output &&
264
+
265
+ # Verify reflog message includes --advance and branch name
266
+ git reflog main -1 --format=%gs >reflog-msg &&
267
+ echo "replay --advance main" >expect-reflog &&
268
+ test_cmp expect-reflog reflog-msg
269
+'
270
+
271
test_done