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

[Patrick Steinhardt <ps@pks.im>]

On Thu, Feb 12, 2026 at 12:19:58PM -0800, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> 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.

Good point, will add.

Patrick