From 1073fa14e14ae119d6025298eafcb3f1c12bd7df Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Mon, 16 Feb 2026 07:45:46 +0100 Subject: builtin/history: replace "--ref-action=print" with "--dry-run" The git-history(1) command has the ability to perform a dry-run that will not end up modifying any references. Instead, we'll only print any ref updates that would happen as a consequence of performing the operation. This mode is somewhat hidden though behind the "--ref-action=print" option. This command line option has its origin in git-replay(1), where it's probably an okayish interface as this command is sitting more on the plumbing side of tools. But git-history(1) is a user-facing tool, and this way of achieving a dry-run is way too technical and thus not very discoverable. Besides usability issues, it also has another issue: the dry-run mode will always operate as if the user wanted to rewrite all branches. But in fact, the user also has the option to only update the HEAD reference, and they might want to perform a dry-run of such an operation, too. We could of course introduce "--ref-action=print-head", but that would become even less ergonomic. Replace "--ref-action=print" with a new "--dry-run" toggle. This new toggle works with both "--ref-action={head,branches}" and is way more discoverable. Add a test to verify that both "--ref-action=" values behave as expected. This patch is best viewed with "--ignore-space-change". Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/git-history.adoc | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-history.adoc b/Documentation/git-history.adoc index 154e262b76..df2900ac2f 100644 --- a/Documentation/git-history.adoc +++ b/Documentation/git-history.adoc @@ -8,7 +8,7 @@ git-history - EXPERIMENTAL: Rewrite history SYNOPSIS -------- [synopsis] -git history reword [--ref-action=(branches|head|print)] +git history reword [--dry-run] [--ref-action=(branches|head)] DESCRIPTION ----------- @@ -60,13 +60,17 @@ The following commands are available to rewrite history in different ways: OPTIONS ------- -`--ref-action=(branches|head|print)`:: +`--dry-run`:: + Do not update any references, but instead print any ref updates in a + format that can be consumed by linkgit:git-update-ref[1]. Necessary new + objects will be written into the repository, so applying these printed + ref updates is generally safe. + +`--ref-action=(branches|head)`:: Control which references will be updated by the command, if any. With `branches`, all local branches that point to commits which are descendants of the original commit will be rewritten. With `head`, only - the current `HEAD` reference will be rewritten. With `print`, all - updates as they would be performed with `branches` are printed in a - format that can be consumed by linkgit:git-update-ref[1]. + the current `HEAD` reference will be rewritten. GIT --- -- cgit v1.3 From 060e602dcb4ce94cd57ccdc4256a136fc36d9c40 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Mon, 16 Feb 2026 07:45:47 +0100 Subject: builtin/history: rename "--ref-action=" to "--update-refs=" With the preceding commit we have changed "--ref-action=" to only control which refs are supposed to be updated, not what happens with them. As a consequence, the option is now somewhat misnamed, as we don't control the action itself anymore. Rename it to "--update-refs=" to better align it with its new use. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/git-history.adoc | 4 ++-- builtin/history.c | 8 ++++---- t/t3451-history-reword.sh | 8 ++++---- 3 files changed, 10 insertions(+), 10 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-history.adoc b/Documentation/git-history.adoc index df2900ac2f..4dbe665ec4 100644 --- a/Documentation/git-history.adoc +++ b/Documentation/git-history.adoc @@ -8,7 +8,7 @@ git-history - EXPERIMENTAL: Rewrite history SYNOPSIS -------- [synopsis] -git history reword [--dry-run] [--ref-action=(branches|head)] +git history reword [--dry-run] [--update-refs=(branches|head)] DESCRIPTION ----------- @@ -66,7 +66,7 @@ OPTIONS objects will be written into the repository, so applying these printed ref updates is generally safe. -`--ref-action=(branches|head)`:: +`--update-refs=(branches|head)`:: Control which references will be updated by the command, if any. With `branches`, all local branches that point to commits which are descendants of the original commit will be rewritten. With `head`, only diff --git a/builtin/history.c b/builtin/history.c index c135361c67..1cf6c668cf 100644 --- a/builtin/history.c +++ b/builtin/history.c @@ -18,7 +18,7 @@ #include "wt-status.h" #define GIT_HISTORY_REWORD_USAGE \ - N_("git history reword [--dry-run] [--ref-action=(branches|head)]") + N_("git history reword [--dry-run] [--update-refs=(branches|head)]") static void change_data_free(void *util, const char *str UNUSED) { @@ -258,7 +258,7 @@ static int setup_revwalk(struct repository *repo, goto out; } else if (!ret) { ret = error(_("rewritten commit must be an ancestor " - "of HEAD when using --ref-action=head")); + "of HEAD when using --update-refs=head")); goto out; } @@ -416,8 +416,8 @@ static int cmd_history_reword(int argc, enum ref_action action = REF_ACTION_DEFAULT; int dry_run = 0; struct option options[] = { - OPT_CALLBACK_F(0, "ref-action", &action, N_(""), - N_("control ref update behavior (branches|head)"), + OPT_CALLBACK_F(0, "update-refs", &action, N_(""), + N_("control which refs should be updated (branches|head)"), PARSE_OPT_NONEG, parse_ref_action), OPT_BOOL('n', "dry-run", &dry_run, N_("perform a dry-run without updating any refs")), diff --git a/t/t3451-history-reword.sh b/t/t3451-history-reword.sh index 702d40dc06..de7b357685 100755 --- a/t/t3451-history-reword.sh +++ b/t/t3451-history-reword.sh @@ -233,7 +233,7 @@ test_expect_success '--dry-run prints ref updates without modifying repo' ' test_commit theirs && git refs list >refs-expect && - reword_with_message --dry-run --ref-action=head base >updates <<-\EOF && + reword_with_message --dry-run --update-refs=head base >updates <<-\EOF && reworded commit EOF git refs list >refs-actual && @@ -258,7 +258,7 @@ test_expect_success '--dry-run prints ref updates without modifying repo' ' ) ' -test_expect_success '--ref-action=head updates only HEAD' ' +test_expect_success '--update-refs=head updates only HEAD' ' test_when_finished "rm -rf repo" && git init repo --initial-branch=main && ( @@ -271,10 +271,10 @@ test_expect_success '--ref-action=head updates only HEAD' ' # When told to update HEAD, only, the command will refuse to # rewrite commits that are not an ancestor of HEAD. - test_must_fail git -c core.editor=false history reword --ref-action=head theirs 2>err && + test_must_fail git -c core.editor=false history reword --update-refs=head theirs 2>err && test_grep "rewritten commit must be an ancestor of HEAD" err && - reword_with_message --ref-action=head base >updates <<-\EOF && + reword_with_message --update-refs=head base >updates <<-\EOF && reworded base EOF expect_log HEAD <<-\EOF && -- cgit v1.3 From 1278a26544e81dddf564fd7730890a7e023ed367 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Mon, 16 Feb 2026 07:45:48 +0100 Subject: Documentation/git-history: document default for "--update-refs=" While we document the values that can be passed to the "--update-refs=" option, we don't give the user any hint what the default behaviour is. Document it. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/git-history.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/git-history.adoc b/Documentation/git-history.adoc index 4dbe665ec4..cc019de697 100644 --- a/Documentation/git-history.adoc +++ b/Documentation/git-history.adoc @@ -70,7 +70,7 @@ OPTIONS Control which references will be updated by the command, if any. With `branches`, all local branches that point to commits which are descendants of the original commit will be rewritten. With `head`, only - the current `HEAD` reference will be rewritten. + the current `HEAD` reference will be rewritten. Defaults to `branches`. GIT --- -- cgit v1.3