Re: [PATCH v2] doc: document rev-list opts in revert, cherry-pick

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 27, 2025, 16:14 UTC
Message-ID: <xmqqjz2o3foe.fsf@gitster.g>
In-Reply-To: <pull.2042.v2.git.git.1756279345929.gitgitgadget@gmail.com>

"Emily Shaffer via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 7 quoted lines

> From: Emily Shaffer <emilyshaffer@google.com>
>
> In f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),
> we added a handful of new options to `git revert` and `git cherry-pick`,
> but did not document them except by example to `cherry-pick` only. We
> have a nice shorthand for adding the rev-list documentation, so let's
> add it now, to both commands.

That's a blast from the past.

Show 10 quoted lines

> diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc
> index 42b41923d5f..03848aa9f21 100644
> --- a/Documentation/git-cherry-pick.adoc
> +++ b/Documentation/git-cherry-pick.adoc
> @@ -174,6 +174,8 @@ fail unless one of `--empty=keep` or `--allow-empty` are specified.
>  
>  include::rerere-options.adoc[]
>  
> +include::rev-list-options.adoc[]
> +

Are there options that rev-list family of commands take that are nonsense in the context of cherry-pick (and revert)?

The rev-list-options.adoc[] file is designed to be included from different places, so for example it omits certain things from appearing in the output. E.g., by doing things like:

    `--ignore-missing`::
            Upon seeing an invalid object name in the input, pretend as if
            the bad input was not given.

    ifndef::git-rev-list[]
    `--bisect`::
            Pretend as if the bad bisection ref `refs/bisect/bad`
            was listed and as if it was followed by `--not` and the good
            bisection refs `refs/bisect/good-*` on the command
            line.
    endif::git-rev-list[]

and not doing

    :git-rev-list: 1
    include::rev-list-options.adoc[]

we can exclude specific parts of the rev-list-options.adoc from inclusion.

I know that the implementation took a blind^Wstupid route to allow everything, but documenting them for unsuspecting general public would make the harm larger. They wouldn't have even imagined to type

    git cherry-pick --graph master

if they weren't told that the command took such a nonsense option. Have you reviewed what is in rev-list-options.adoc and thought about excluding certain parts when the file is included in either git-cherry-pick.adoc or git-revert.adoc?