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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 21, 2025, 21:15 UTC
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:

Show 21 quoted lines

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

Show 19 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.

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.