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

[Junio C Hamano <gitster@pobox.com>]

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

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

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