replay: make atomic ref updates the default behavior

The git replay command currently outputs update commands that must be
piped to git update-ref --stdin to actually update references:

    git replay --onto main topic1..topic2 | git update-ref --stdin

This design has significant limitations for server-side operations. The
two-command pipeline creates coordination complexity, provides no atomic
transaction guarantees by default, and complicates automation in bare
repository environments where git replay is primarily used.

During extensive mailing list discussion, multiple maintainers identified
that the current approach forces users to opt-in to atomic behavior rather
than defaulting to the safer, more reliable option. Elijah Newren noted
that the experimental status explicitly allows such behavior changes, while
Patrick Steinhardt highlighted performance concerns with individual ref
updates in the reftable backend.

The core issue is that git replay was designed around command output rather
than direct action. This made sense for a plumbing tool, but creates barriers
for the primary use case: server-side operations that need reliable, atomic
ref updates without pipeline complexity.

This patch changes the default behavior to update refs directly using Git's
ref transaction API:

    git replay --onto main topic1..topic2
    # No output; all refs updated atomically or none

The implementation uses ref_store_transaction_begin() with atomic mode by
default, ensuring all ref updates succeed or all fail as a single operation.
This leverages git replay's existing server-side strengths (in-memory operation,
no work tree requirement) while adding the atomic guarantees that server
operations require.

For users needing the traditional pipeline workflow, --output-commands
preserves the original behavior:

    git replay --output-commands --onto main topic1..topic2 | git update-ref --stdin

The --allow-partial option enables partial failure tolerance. However, following
maintainer feedback, it implements a "strict success" model: the command exits
with code 0 only if ALL ref updates succeed, and exits with code 1 if ANY
updates fail. This ensures that --allow-partial changes error reporting style
(warnings vs hard errors) but not success criteria, handling edge cases like
"no updates needed" cleanly.

Implementation details:
- Empty commit ranges now return success (exit code 0) rather than failure,
  as no commits to replay is a valid successful operation
- Added comprehensive test coverage with 12 new tests covering atomic behavior,
  option validation, bare repository support, and edge cases
- Fixed test isolation issues to prevent branch state contamination between tests
- Maintains C89 compliance and follows Git's established coding conventions
- Refactored option validation to use die_for_incompatible_opt2() for both
  --advance/--contained and --allow-partial/--output-commands conflicts,
  providing consistent error reporting
- Fixed --allow-partial exit code behavior to implement "strict success" model
  where any ref update failures result in exit code 1, even with partial tolerance
- Updated documentation with proper line wrapping, consistent terminology using
  "old default behavior", performance context, and reorganized examples for clarity
- Eliminates individual ref updates (refs_update_ref calls) that perform
  poorly with reftable backend
- Uses only batched ref transactions for optimal performance across all
  ref backends
- Avoids naming collision with git rebase --update-refs by using distinct
  option names
- Defaults to atomic behavior while preserving pipeline compatibility

The result is a command that works better for its primary use case (server-side
operations) while maintaining full backward compatibility for existing workflows.

Signed-off-by: Siddharth Asthana <[email protected]>
Signed-off-by: Junio C Hamano <[email protected]>

Author: edith007

Documentation/git-replay.adoc

@@ -9,16 +9,16 @@ git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos t
 SYNOPSIS
 --------
 [verse]
-(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) <revision-range>...
+(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) [--output-commands | --allow-partial] <revision-range>...
 
 DESCRIPTION
 -----------
 
 Takes ranges of commits and replays them onto a new location. Leaves
-the working tree and the index untouched, and updates no references.
-The output of this command is meant to be used as input to
-`git update-ref --stdin`, which would update the relevant branches
-(see the OUTPUT section below).
+the working tree and the index untouched, and by default updates the
+relevant references using atomic transactions. Use `--output-commands`
+to get the old default behavior where update commands that can be piped
+to `git update-ref --stdin` are emitted (see the OUTPUT section below).
 
 THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
 
@@ -42,6 +42,20 @@ When `--advance` is specified, the update-ref command(s) in the output
 will update the branch passed as an argument to `--advance` to point at
 the new commits (in other words, this mimics a cherry-pick operation).
 
+--output-commands::
+	Output update-ref commands instead of updating refs directly.
+	When this option is used, the output can be piped to `git update-ref --stdin`
+	for successive, relatively slow, ref updates. This is equivalent to the
+	old default behavior.
+
+--allow-partial::
+	Allow some ref updates to succeed even if others fail. By default,
+	ref updates are atomic (all succeed or all fail). With this option,
+	failed updates are reported as warnings rather than causing the entire
+	command to fail. The command exits with code 0 only if all updates
+	succeed; any failures result in exit code 1. Cannot be used with
+	`--output-commands`.
+
 <revision-range>::
 	Range of commits to replay. More than one <revision-range> can
 	be passed, but in `--advance <branch>` mode, they should have
@@ -54,15 +68,20 @@ include::rev-list-options.adoc[]
 OUTPUT
 ------
 
-When there are no conflicts, the output of this command is usable as
-input to `git update-ref --stdin`.  It is of the form:
+By default, when there are no conflicts, this command updates the relevant
+references using atomic transactions and produces no output. All ref updates
+succeed or all fail (atomic behavior). Use `--allow-partial` to allow some
+updates to succeed while others fail.
+
+When `--output-commands` is used, the output is usable as input to
+`git update-ref --stdin`. It is of the form:
 
 	update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
 	update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
 	update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}
 
 where the number of refs updated depends on the arguments passed and
-the shape of the history being replayed.  When using `--advance`, the
+the shape of the history being replayed. When using `--advance`, the
 number of refs updated is always one, but for `--onto`, it can be one
 or more (rebasing multiple branches simultaneously is supported).
 
@@ -77,41 +96,70 @@ is something other than 0 or 1.
 EXAMPLES
 --------
 
-To simply rebase `mybranch` onto `target`:
+To simply rebase `mybranch` onto `target` (default behavior):
 
 ------------
 $ git replay --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
-update refs/heads/target ${NEW_target_HASH} ${OLD_target_HASH}
 ------------
 
 Note that the first two examples replay the exact same commits and on
 top of the exact same new base, they only differ in that the first
-provides instructions to make mybranch point at the new commits and
-the second provides instructions to make target point at them.
+updates mybranch to point at the new commits and the second updates
+target to point at them.
+
+To get the old default behavior where update commands are emitted:
+
+------------
+$ git replay --output-commands --onto target origin/main..mybranch
+update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH}
+------------
+
+To rebase multiple branches with partial failure tolerance:
+
+------------
+$ git replay --allow-partial --contained --onto origin/main origin/main..tipbranch
+------------
 
 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
+------------
+
+This automatically finds and rebases all branches contained within the
+`origin/main..tipbranch` range.
+
+Or if you want to see the old default behavior where update commands are emitted:
+
+------------
+$ git replay --output-commands --contained --onto origin/main origin/main..tipbranch
 update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
 update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
 update refs/heads/tipbranch ${NEW_tipbranch_HASH} ${OLD_tipbranch_HASH}
 ------------
 
 When calling `git replay`, one does not need to specify a range of
 commits to replay using the syntax `A..B`; any range expression will
-do:
+do. Here's an example where you explicitly specify which branches to rebase:
 
 ------------
 $ git replay --onto origin/main ^base branch1 branch2 branch3
+------------
+
+This gives you explicit control over exactly which branches are rebased,
+unlike the previous `--contained` example which automatically discovers them.
+
+To see the update commands that would be executed:
+
+------------
+$ git replay --output-commands --onto origin/main ^base branch1 branch2 branch3
 update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
 update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
 update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}

builtin/replay.c

@@ -284,6 +284,28 @@ static struct commit *pick_regular_commit(struct repository *repo,
 	return create_commit(repo, result->tree, pickme, replayed_base);
 }
 
+static int add_ref_to_transaction(struct ref_transaction *transaction,
+				  const char *refname,
+				  const struct object_id *new_oid,
+				  const struct object_id *old_oid,
+				  struct strbuf *err)
+{
+	return ref_transaction_update(transaction, refname, new_oid, old_oid,
+				      NULL, NULL, 0, "git replay", err);
+}
+
+static void print_rejected_update(const char *refname,
+				  const struct object_id *old_oid UNUSED,
+				  const struct object_id *new_oid UNUSED,
+				  const char *old_target UNUSED,
+				  const char *new_target UNUSED,
+				  enum ref_transaction_error err,
+				  void *cb_data UNUSED)
+{
+	const char *reason = ref_transaction_error_msg(err);
+	warning(_("failed to update %s: %s"), refname, reason);
+}
+
 int cmd_replay(int argc,
 	       const char **argv,
 	       const char *prefix,
@@ -294,6 +316,8 @@ int cmd_replay(int argc,
 	struct commit *onto = NULL;
 	const char *onto_name = NULL;
 	int contained = 0;
+	int output_commands = 0;
+	int allow_partial = 0;
 
 	struct rev_info revs;
 	struct commit *last_commit = NULL;
@@ -302,12 +326,15 @@ int cmd_replay(int argc,
 	struct merge_result result;
 	struct strset *update_refs = NULL;
 	kh_oid_map_t *replayed_commits;
+	struct ref_transaction *transaction = NULL;
+	struct strbuf transaction_err = STRBUF_INIT;
+	int commits_processed = 0;
 	int ret = 0;
 
-	const char * const replay_usage[] = {
+	const char *const replay_usage[] = {
 		N_("(EXPERIMENTAL!) git replay "
 		   "([--contained] --onto <newbase> | --advance <branch>) "
-		   "<revision-range>..."),
+		   "[--output-commands | --allow-partial] <revision-range>..."),
 		NULL
 	};
 	struct option replay_options[] = {
@@ -319,6 +346,10 @@ int cmd_replay(int argc,
 			   N_("replay onto given commit")),
 		OPT_BOOL(0, "contained", &contained,
 			 N_("advance all branches contained in revision-range")),
+		OPT_BOOL(0, "output-commands", &output_commands,
+			 N_("output update commands instead of updating refs")),
+		OPT_BOOL(0, "allow-partial", &allow_partial,
+			 N_("allow some ref updates to succeed even if others fail")),
 		OPT_END()
 	};
 
@@ -330,9 +361,12 @@ int cmd_replay(int argc,
 		usage_with_options(replay_usage, replay_options);
 	}
 
-	if (advance_name_opt && contained)
-		die(_("options '%s' and '%s' cannot be used together"),
-		    "--advance", "--contained");
+	die_for_incompatible_opt2(!!advance_name_opt, "--advance",
+				  contained, "--contained");
+
+	die_for_incompatible_opt2(allow_partial, "--allow-partial",
+				  output_commands, "--output-commands");
+
 	advance_name = xstrdup_or_null(advance_name_opt);
 
 	repo_init_revisions(repo, &revs, prefix);
@@ -389,6 +423,17 @@ int cmd_replay(int argc,
 	determine_replay_mode(repo, &revs.cmdline, onto_name, &advance_name,
 			      &onto, &update_refs);
 
+	if (!output_commands) {
+		unsigned int transaction_flags = allow_partial ? REF_TRANSACTION_ALLOW_FAILURE : 0;
+		transaction = ref_store_transaction_begin(get_main_ref_store(repo),
+							  transaction_flags,
+							  &transaction_err);
+		if (!transaction) {
+			ret = error(_("failed to begin ref transaction: %s"), transaction_err.buf);
+			goto cleanup;
+		}
+	}
+
 	if (!onto) /* FIXME: Should handle replaying down to root commit */
 		die("Replaying down to root commit is not supported yet!");
 
@@ -407,6 +452,8 @@ int cmd_replay(int argc,
 		khint_t pos;
 		int hr;
 
+		commits_processed = 1;
+
 		if (!commit->parents)
 			die(_("replaying down to root commit is not supported yet!"));
 		if (commit->parents->next)
@@ -434,21 +481,52 @@ int cmd_replay(int argc,
 			if (decoration->type == DECORATION_REF_LOCAL &&
 			    (contained || strset_contains(update_refs,
 							  decoration->name))) {
-				printf("update %s %s %s\n",
-				       decoration->name,
-				       oid_to_hex(&last_commit->object.oid),
-				       oid_to_hex(&commit->object.oid));
+				if (output_commands) {
+					printf("update %s %s %s\n",
+					       decoration->name,
+					       oid_to_hex(&last_commit->object.oid),
+					       oid_to_hex(&commit->object.oid));
+				} else if (add_ref_to_transaction(transaction, decoration->name,
+								  &last_commit->object.oid,
+								  &commit->object.oid,
+								  &transaction_err) < 0) {
+					ret = error(_("failed to add ref update to transaction: %s"), transaction_err.buf);
+					goto cleanup;
+				}
 			}
 			decoration = decoration->next;
 		}
 	}
 
 	/* In --advance mode, advance the target ref */
 	if (result.clean == 1 && advance_name) {
-		printf("update %s %s %s\n",
-		       advance_name,
-		       oid_to_hex(&last_commit->object.oid),
-		       oid_to_hex(&onto->object.oid));
+		if (output_commands) {
+			printf("update %s %s %s\n",
+			       advance_name,
+			       oid_to_hex(&last_commit->object.oid),
+			       oid_to_hex(&onto->object.oid));
+		} else if (add_ref_to_transaction(transaction, advance_name,
+						  &last_commit->object.oid,
+						  &onto->object.oid,
+						  &transaction_err) < 0) {
+			ret = error(_("failed to add ref update to transaction: %s"), transaction_err.buf);
+			goto cleanup;
+		}
+	}
+
+	/* Commit the ref transaction if we have one */
+	if (transaction && result.clean == 1) {
+		if (ref_transaction_commit(transaction, &transaction_err)) {
+			if (allow_partial) {
+				warning(_("some ref updates failed: %s"), transaction_err.buf);
+				ref_transaction_for_each_rejected_update(transaction,
+									 print_rejected_update, NULL);
+				ret = 0; /* Set failure even with allow_partial */
+			} else {
+				ret = error(_("failed to update refs: %s"), transaction_err.buf);
+				goto cleanup;
+			}
+		}
 	}
 
 	merge_finalize(&merge_opt, &result);
@@ -457,9 +535,17 @@ int cmd_replay(int argc,
 		strset_clear(update_refs);
 		free(update_refs);
 	}
-	ret = result.clean;
+
+	/* Handle empty ranges: if no commits were processed, treat as success */
+	if (!commits_processed)
+		ret = 1; /* Success - no commits to replay is not an error */
+	else
+		ret = result.clean;
 
 cleanup:
+	if (transaction)
+		ref_transaction_free(transaction);
+	strbuf_release(&transaction_err);
 	release_revisions(&revs);
 	free(advance_name);