Merge branch 'sa/replay-atomic-ref-updates'

"git replay" (experimental) learned to perform ref updates itself
in a transaction by default, instead of emitting where each refs
should point at and leaving the actual update to another command.

* sa/replay-atomic-ref-updates:
  replay: add replay.refAction config option
  replay: make atomic ref updates the default behavior
  replay: use die_for_incompatible_opt2() for option validation
This commit is contained in:
Junio C Hamano
2025-11-24 15:46:40 -08:00
4 changed files with 277 additions and 43 deletions

View File

@@ -0,0 +1,11 @@
replay.refAction::
Specifies the default mode for handling reference updates in
`git replay`. The value can be:
+
--
* `update`: Update refs directly using an atomic transaction (default behavior).
* `print`: Output update-ref commands for pipeline use.
--
+
This setting can be overridden with the `--ref-action` command-line option.
When not configured, `git replay` defaults to `update` mode.

View File

@@ -9,15 +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>) [--ref-action[=<mode>]] <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
the working tree and the index untouched. By default, updates the
relevant references using an atomic transaction (all refs update or
none). Use `--ref-action=print` to avoid automatic ref updates and
instead get update commands that can be piped to `git update-ref --stdin`
(see the OUTPUT section below).
THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
@@ -29,18 +30,29 @@ OPTIONS
Starting point at which to create the new commits. May be any
valid commit, and not just an existing branch name.
+
When `--onto` is specified, the update-ref command(s) in the output will
update the branch(es) in the revision range to point at the new
commits, similar to the way how `git rebase --update-refs` updates
multiple branches in the affected range.
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>::
Starting point at which to create the new commits; must be a
branch name.
+
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).
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.
--ref-action[=<mode>]::
Control how references are updated. The mode can be:
+
--
* `update` (default): Update refs directly using an atomic transaction.
All refs are updated or none are (all-or-nothing behavior).
* `print`: Output update-ref commands for pipeline use. This is the
traditional behavior where output can be piped to `git update-ref --stdin`.
--
+
The default mode can be configured via the `replay.refAction` configuration variable.
<revision-range>::
Range of commits to replay. More than one <revision-range> can
@@ -54,8 +66,11 @@ 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, or with `--ref-action=update`, this command produces no output on
success, as refs are updated directly using an atomic transaction.
When using `--ref-action=print`, 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}
@@ -81,6 +96,14 @@ To simply rebase `mybranch` onto `target`:
------------
$ git replay --onto target origin/main..mybranch
------------
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
update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH}
------------
@@ -88,33 +111,29 @@ 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.
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
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}
------------
All three branches (`branch1`, `branch2`, and `tipbranch`) are updated
atomically.
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:
------------
$ git replay --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}
------------
This will simultaneously rebase `branch1`, `branch2`, and `branch3`,

View File

@@ -8,6 +8,7 @@
#include "git-compat-util.h"
#include "builtin.h"
#include "config.h"
#include "environment.h"
#include "hex.h"
#include "lockfile.h"
@@ -20,6 +21,11 @@
#include <oidset.h>
#include <tree.h>
enum ref_action_mode {
REF_ACTION_UPDATE,
REF_ACTION_PRINT,
};
static const char *short_commit_name(struct repository *repo,
struct commit *commit)
{
@@ -284,6 +290,54 @@ static struct commit *pick_regular_commit(struct repository *repo,
return create_commit(repo, result->tree, pickme, replayed_base);
}
static enum ref_action_mode parse_ref_action_mode(const char *ref_action, const char *source)
{
if (!ref_action || !strcmp(ref_action, "update"))
return REF_ACTION_UPDATE;
if (!strcmp(ref_action, "print"))
return REF_ACTION_PRINT;
die(_("invalid %s value: '%s'"), source, ref_action);
}
static enum ref_action_mode get_ref_action_mode(struct repository *repo, const char *ref_action)
{
const char *config_value = NULL;
/* Command line option takes precedence */
if (ref_action)
return parse_ref_action_mode(ref_action, "--ref-action");
/* Check config value */
if (!repo_config_get_string_tmp(repo, "replay.refAction", &config_value))
return parse_ref_action_mode(config_value, "replay.refAction");
/* Default to update mode */
return REF_ACTION_UPDATE;
}
static int handle_ref_update(enum ref_action_mode mode,
struct ref_transaction *transaction,
const char *refname,
const struct object_id *new_oid,
const struct object_id *old_oid,
const char *reflog_msg,
struct strbuf *err)
{
switch (mode) {
case REF_ACTION_PRINT:
printf("update %s %s %s\n",
refname,
oid_to_hex(new_oid),
oid_to_hex(old_oid));
return 0;
case REF_ACTION_UPDATE:
return ref_transaction_update(transaction, refname, new_oid, old_oid,
NULL, NULL, 0, reflog_msg, err);
default:
BUG("unknown ref_action_mode %d", mode);
}
}
int cmd_replay(int argc,
const char **argv,
const char *prefix,
@@ -294,6 +348,8 @@ int cmd_replay(int argc,
struct commit *onto = NULL;
const char *onto_name = NULL;
int contained = 0;
const char *ref_action = NULL;
enum ref_action_mode ref_mode;
struct rev_info revs;
struct commit *last_commit = NULL;
@@ -302,12 +358,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;
struct strbuf reflog_msg = STRBUF_INIT;
int ret = 0;
const char * const replay_usage[] = {
const char *const replay_usage[] = {
N_("(EXPERIMENTAL!) git replay "
"([--contained] --onto <newbase> | --advance <branch>) "
"<revision-range>..."),
"[--ref-action[=<mode>]] <revision-range>..."),
NULL
};
struct option replay_options[] = {
@@ -319,6 +378,9 @@ int cmd_replay(int argc,
N_("replay onto given commit")),
OPT_BOOL(0, "contained", &contained,
N_("advance all branches contained in revision-range")),
OPT_STRING(0, "ref-action", &ref_action,
N_("mode"),
N_("control ref update behavior (update|print)")),
OPT_END()
};
@@ -330,9 +392,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");
/* Parse ref action mode from command line or config */
ref_mode = get_ref_action_mode(repo, ref_action);
advance_name = xstrdup_or_null(advance_name_opt);
repo_init_revisions(repo, &revs, prefix);
@@ -389,6 +454,24 @@ int cmd_replay(int argc,
determine_replay_mode(repo, &revs.cmdline, onto_name, &advance_name,
&onto, &update_refs);
/* Build reflog message */
if (advance_name_opt)
strbuf_addf(&reflog_msg, "replay --advance %s", advance_name_opt);
else
strbuf_addf(&reflog_msg, "replay --onto %s",
oid_to_hex(&onto->object.oid));
/* Initialize ref transaction if using update mode */
if (ref_mode == REF_ACTION_UPDATE) {
transaction = ref_store_transaction_begin(get_main_ref_store(repo),
0, &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!");
@@ -434,10 +517,16 @@ 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 (handle_ref_update(ref_mode, transaction,
decoration->name,
&last_commit->object.oid,
&commit->object.oid,
reflog_msg.buf,
&transaction_err) < 0) {
ret = error(_("failed to update ref '%s': %s"),
decoration->name, transaction_err.buf);
goto cleanup;
}
}
decoration = decoration->next;
}
@@ -445,10 +534,24 @@ int cmd_replay(int argc,
/* 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 (handle_ref_update(ref_mode, transaction, advance_name,
&last_commit->object.oid,
&onto->object.oid,
reflog_msg.buf,
&transaction_err) < 0) {
ret = error(_("failed to update ref '%s': %s"),
advance_name, 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)) {
ret = error(_("failed to commit ref transaction: %s"),
transaction_err.buf);
goto cleanup;
}
}
merge_finalize(&merge_opt, &result);
@@ -460,6 +563,10 @@ int cmd_replay(int argc,
ret = result.clean;
cleanup:
if (transaction)
ref_transaction_free(transaction);
strbuf_release(&transaction_err);
strbuf_release(&reflog_msg);
release_revisions(&revs);
free(advance_name);

View File

@@ -52,7 +52,7 @@ test_expect_success 'setup bare' '
'
test_expect_success 'using replay to rebase two branches, one on top of other' '
git replay --onto main topic1..topic2 >result &&
git replay --ref-action=print --onto main topic1..topic2 >result &&
test_line_count = 1 result &&
@@ -68,7 +68,7 @@ test_expect_success 'using replay to rebase two branches, one on top of other' '
'
test_expect_success 'using replay on bare repo to rebase two branches, one on top of other' '
git -C bare replay --onto main topic1..topic2 >result-bare &&
git -C bare replay --ref-action=print --onto main topic1..topic2 >result-bare &&
test_cmp expect result-bare
'
@@ -86,7 +86,7 @@ test_expect_success 'using replay to perform basic cherry-pick' '
# 2nd field of result is refs/heads/main vs. refs/heads/topic2
# 4th field of result is hash for main instead of hash for topic2
git replay --advance main topic1..topic2 >result &&
git replay --ref-action=print --advance main topic1..topic2 >result &&
test_line_count = 1 result &&
@@ -102,7 +102,7 @@ test_expect_success 'using replay to perform basic cherry-pick' '
'
test_expect_success 'using replay on bare repo to perform basic cherry-pick' '
git -C bare replay --advance main topic1..topic2 >result-bare &&
git -C bare replay --ref-action=print --advance main topic1..topic2 >result-bare &&
test_cmp expect result-bare
'
@@ -115,7 +115,7 @@ test_expect_success 'replay fails when both --advance and --onto are omitted' '
'
test_expect_success 'using replay to also rebase a contained branch' '
git replay --contained --onto main main..topic3 >result &&
git replay --ref-action=print --contained --onto main main..topic3 >result &&
test_line_count = 2 result &&
cut -f 3 -d " " result >new-branch-tips &&
@@ -139,12 +139,12 @@ test_expect_success 'using replay to also rebase a contained branch' '
'
test_expect_success 'using replay on bare repo to also rebase a contained branch' '
git -C bare replay --contained --onto main main..topic3 >result-bare &&
git -C bare replay --ref-action=print --contained --onto main main..topic3 >result-bare &&
test_cmp expect result-bare
'
test_expect_success 'using replay to rebase multiple divergent branches' '
git replay --onto main ^topic1 topic2 topic4 >result &&
git replay --ref-action=print --onto main ^topic1 topic2 topic4 >result &&
test_line_count = 2 result &&
cut -f 3 -d " " result >new-branch-tips &&
@@ -168,7 +168,7 @@ test_expect_success 'using replay to rebase multiple divergent branches' '
'
test_expect_success 'using replay on bare repo to rebase multiple divergent branches, including contained ones' '
git -C bare replay --contained --onto main ^main topic2 topic3 topic4 >result &&
git -C bare replay --ref-action=print --contained --onto main ^main topic2 topic3 topic4 >result &&
test_line_count = 4 result &&
cut -f 3 -d " " result >new-branch-tips &&
@@ -217,4 +217,101 @@ test_expect_success 'merge.directoryRenames=false' '
--onto rename-onto rename-onto..rename-from
'
test_expect_success 'default atomic behavior updates refs directly' '
# Use a separate branch to avoid contaminating topic2 for later tests
git branch test-atomic topic2 &&
test_when_finished "git branch -D test-atomic" &&
# Test default atomic behavior (no output, refs updated)
git replay --onto main topic1..test-atomic >output &&
test_must_be_empty output &&
# Verify ref was updated
git log --format=%s test-atomic >actual &&
test_write_lines E D M L B A >expect &&
test_cmp expect actual &&
# Verify reflog message includes SHA of onto commit
git reflog test-atomic -1 --format=%gs >reflog-msg &&
ONTO_SHA=$(git rev-parse main) &&
echo "replay --onto $ONTO_SHA" >expect-reflog &&
test_cmp expect-reflog reflog-msg
'
test_expect_success 'atomic behavior in bare repository' '
# Store original state for cleanup
START=$(git -C bare rev-parse topic2) &&
test_when_finished "git -C bare update-ref refs/heads/topic2 $START" &&
# Test atomic updates work in bare repo
git -C bare replay --onto main topic1..topic2 >output &&
test_must_be_empty output &&
# Verify ref was updated in bare repo
git -C bare log --format=%s topic2 >actual &&
test_write_lines E D M L B A >expect &&
test_cmp expect actual
'
test_expect_success 'reflog message for --advance mode' '
# Store original state
START=$(git rev-parse main) &&
test_when_finished "git update-ref refs/heads/main $START" &&
# Test --advance mode reflog message
git replay --advance main topic1..topic2 >output &&
test_must_be_empty output &&
# Verify reflog message includes --advance and branch name
git reflog main -1 --format=%gs >reflog-msg &&
echo "replay --advance main" >expect-reflog &&
test_cmp expect-reflog reflog-msg
'
test_expect_success 'replay.refAction=print config option' '
# Store original state
START=$(git rev-parse topic2) &&
test_when_finished "git branch -f topic2 $START" &&
# Test with config set to print
test_config replay.refAction print &&
git replay --onto main topic1..topic2 >output &&
test_line_count = 1 output &&
test_grep "^update refs/heads/topic2 " output
'
test_expect_success 'replay.refAction=update config option' '
# Store original state
START=$(git rev-parse topic2) &&
test_when_finished "git branch -f topic2 $START" &&
# Test with config set to update
test_config replay.refAction update &&
git replay --onto main topic1..topic2 >output &&
test_must_be_empty output &&
# Verify ref was updated
git log --format=%s topic2 >actual &&
test_write_lines E D M L B A >expect &&
test_cmp expect actual
'
test_expect_success 'command-line --ref-action overrides config' '
# Store original state
START=$(git rev-parse topic2) &&
test_when_finished "git branch -f topic2 $START" &&
# Set config to update but use --ref-action=print
test_config replay.refAction update &&
git replay --ref-action=print --onto main topic1..topic2 >output &&
test_line_count = 1 output &&
test_grep "^update refs/heads/topic2 " output
'
test_expect_success 'invalid replay.refAction value' '
test_config replay.refAction invalid &&
test_must_fail git replay --onto main topic1..topic2 2>error &&
test_grep "invalid.*replay.refAction.*value" error
'
test_done