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

> On Tuesday, 19 August 2025 12:56:01 CEST Patrick Steinhardt wrote:
> > 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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~