From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 21 Oct 2025 21:15:10 GMT
Subject: Re: [PATCH v5 05/12] builtin: add new "history" command
Message-ID: <xmqqikg8t0rl.fsf@gitster.g>
In-Reply-To: <20251021-b4-pks-history-builtin-v5-5-78d23f578fe6@pks.im>

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.

> +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.

The remainder of this step seems a bog standard "here is how you add
an empty shell for a new command" and I didn't see anything fishy in
it.