Subject: Re: [PATCH RFC 05/11] builtin/history: implement "drop" subcommand

From: Jean-Noël AVILA <[email-masked]>
Date: Sat, 23 Aug 2025 18:15:08 +0200

On Tuesday, 19 August 2025 12:56:01 CEST Patrick Steinhardt wrote:
> It is a fairly common operation to perform an interactive rebase so that
> one of the commits can be dropped from history. Doing this is not very
> hard in general, but still requires the user to perform multiple steps:
> 
>   1. Identify the commit in question that is to be dropped.
> 
>   2. Perform an interactive rebase on top of that commit's parent.
> 
>   3. Edit the instruction sheet to drop that commit.
> 
> This is needlessly complex for such a supposedly-trivial operation.
> Furthermore, the second step doesn't account for certain edge cases like
> for example dropping the root commit.
> 
> Introduce a new "drop" subcommand to make this use case significantly
> simpler: all the user needs to do is to say `git history drop $COMMIT`
> and they're done.
> 
> Note that for now, this command only allows users to drop a single
> commit at once. It should be easy enough though to expand the command at
> a later point in time to support dropping whole commit ranges.
> 
> Signed-off-by: Patrick Steinhardt <[email-masked]>
> ---
>  Documentation/git-history.adoc |  27 +++-
>  builtin/history.c              | 297 ++++++++++++++++++++++++++++++++++++++
++-
>  t/meson.build                  |   3 +-
>  t/t3450-history-drop.sh        | 127 ++++++++++++++++++
>  4 files changed, 449 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/git-history.adoc b/Documentation/git-history.adoc
> index 9dafb8fc16..3012445ddc 100644
> --- a/Documentation/git-history.adoc
> +++ b/Documentation/git-history.adoc
> @@ -8,7 +8,7 @@ git-history - Rewrite history of the current branch
>  SYNOPSIS
>  --------
>  [synopsis]
> -git history [<options>]
> +git history drop [<options>] <revision>
> 

Grepping through the documentation for the <revision> placeholder does not 
yield a lot of matches. Can <revision> be replaced by <commit> or <commit-ish>  
in this context; these ones seem widely used.

>  DESCRIPTION
>  -----------
> @@ -31,6 +31,31 @@ COMMANDS
>  This command requires a subcommand. Several subcommands are available to
>  rewrite history in different ways.
> 
> +drop <revision>::

My linting patch series[1] does not catch this kind of synopsis miss, but 
here, backticks are missing because this is a part of synopsis:

`drop <revision>`::

> +	Drop a commit from the history and reapply all children of that
> +	commit on top of the commit's parent. The commit that is to be
> +	dropped must be reachable from the current `HEAD` commit.
> ++
> +Dropping the root commit converts the child of that commit into the new
> +root commit. It is invalid to drop a root commit that does not have any
> +child commits, as that would lead to an empty branch.
> +
> +EXAMPLES
> +--------
> +
> +* Drop a commit from history.
> ++

As the examples are quite long, it would make sense to declare each example as 
a sub-section:

Drop a commit from history
~~~~~~~~~~~~~~~~~~~~~~~~~~

> +----------
> +$ git log --oneline
> +2d4cd6d third
> +125a0f3 second
> +e098c27 first
> +$ git history drop HEAD~
> +$ git log
> +b1bc1bd third
> +e098c27 first
> +----------
> +
>  CONFIGURATION
>  -------------
>