Re: [PATCH v5 05/12] builtin: add new "history" command

From: Patrick Steinhardt <ps@pks.im>
Date: Oct 27, 2025, 09:57 UTC
Message-ID: <aP9B8yd0JJL9nue8@pks.im>
In-Reply-To: <xmqqikg8t0rl.fsf@gitster.g>

On Tue, Oct 21, 2025 at 02:15:10PM -0700, Junio C Hamano wrote:

Show 31 quoted lines

> Patrick Steinhardt <ps@pks.im> writes:
> 
> > diff --git a/Documentation/git-history.adoc b/Documentation/git-history.adoc
> > new file mode 100644
> > index 00000000000..57560525a70
> > --- /dev/null
> > +++ b/Documentation/git-history.adoc
> > @@ -0,0 +1,45 @@
> > +git-history(1)
> > +==============
> > +
> > +NAME
> > +----
> > +git-history - EXPERIMENTAL: Rewrite history of the current branch
> >
> >
> > +SYNOPSIS
> > +--------
> > +[synopsis]
> > +git history [<options>]
> > +
> > +DESCRIPTION
> > +-----------
> 
> We would want to make sure that all experimental things identify
> themselves in a similar way.
> 
> The way how replay identifies itself as experimental, which this
> patch is modeled after, is somewhat different from what is done by
> backfill, for-each-repo, last-modified, and sparse-checkout
> commands.

I guess the only thing that's different with git-replay(1) is that we also have the `(EXPERIMENTAL!)` tag in the synopsis. No other man page does that as far as I can see.

But yeah, I agree that things should be consistent here. I think the most sensible thing to do is to:

  - Have the "EXPERIMENTAL:" tag in the NAME section.

  - Have "THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE." in the
    DESCRIPTION section, ideally after the first summarizing sentence.

Show 25 quoted lines

> > +Rewrite history by rearranging or modifying specific commits in the
> > +history.
> > +
> > +This command is similar to linkgit:git-rebase[1] and uses the same
> > +underlying machinery. You should use rebases if you want to reapply a range of
> > +commits onto a different base, or interactive rebases if you want to edit a
> > +range of commits.
> > +
> > +Note that this command does not (yet) work with histories that contain
> > +merges. You should use linkgit:git-rebase[1] with the `--rebase-merges`
> > +flag instead.
> > +
> > +THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
> > +
> > +COMMANDS
> > +--------
> > +
> > +This command requires a subcommand. Several subcommands are available to
> > +rewrite history in different ways:
> 
> Looking at "refs", "repo" and "sparse-checkout", none of them say
> "requires a subcommand", even though they do.  It would probably be
> obvious from the syntax, so drop the first sentence, perhaps?
> 
> And "subcommand" -> "command" to match the section title.

Makes sense.

Thanks!

Patrick