Subject: Re: [PATCH 3/4] builtin/history: replace "--ref-action=print" with "--dry-run"

From: Junio C Hamano <[email-masked]>
Date: Thu, 12 Feb 2026 12:19:58 -0800

Patrick Steinhardt <[email-masked]> writes:

> 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-actoin=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 "--dry-run" mode still creates necessary new objects, right?

Describing this "--dry-run" as not updating any refs is a very good
thing, which is what the documentation update says, but at the same
time, we should clearly promise that the necessary new objects are
still created, so should the user then choose to update refs to
point at the reported objects, it will not result in a repository
corruption.

Other than that, looking good.