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

From: Phillip Wood <phillip.wood123@gmail.com>
Date: Aug 27, 2025, 09:41 UTC
Message-ID: <c856cecb-ab70-4c43-a952-cf0350c7949b@gmail.com>
In-Reply-To: <pull.2042.v2.git.git.1756279345929.gitgitgadget@gmail.com>

Hi Emily

On 27/08/2025 08:22, Emily Shaffer via GitGitGadget wrote:

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.

I agree that it would be helpful to have a some rev-list options included here but this adds a huge amount of text to the man page which comes before the documentation for frequently used options like "--continue". I'm not sure all of the new text is relevant to cherry-pick and revert. For instance do we need to document --bisect, -cherry-mark and --boundary here? I'm not sure the History Simplification and Commit Formatting sections are relevant either. There are already a bunch of ifdefs in rev-list-options.adoc that change what's included depending on which command we're documenting, maybe we should add some more for the cherry-pick and revert documentation?

Thanks

Phillip> Reported-by: Andrew Jeffrey <andrew@aj.id.au>

Show 79 quoted lines

> Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
> ---
>      cherry-pick: document rev-list options
>      
>      Ach, sorry for the noise, turns out it touched both revert and
>      cherry-pick, might as well do the docs for both.
> 
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2042%2Fnasamuffin%2Fcherry-pick-docs-v2
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2042/nasamuffin/cherry-pick-docs-v2
> Pull-Request: https://github.com/git/git/pull/2042
> 
> Range-diff vs v1:
> 
>   1:  fa352ccda08 ! 1:  f41cb4e8abc cherry-pick: document rev-list options
>       @@ Metadata
>        Author: Emily Shaffer <emilyshaffer@google.com>
>        
>         ## Commit message ##
>       -    cherry-pick: document rev-list options
>       +    doc: document rev-list opts in revert, cherry-pick
>        
>            In f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),
>       -    we added a handful of new options to `git cherry-pick`, but did not
>       -    document them except by example. We have a nice shorthand for adding the
>       -    rev-list documentation, so let's add it now.
>       +    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.
>        
>            Reported-by: Andrew Jeffrey <andrew@aj.id.au>
>            Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
>       @@ Documentation/git-cherry-pick.adoc: fail unless one of `--empty=keep` or `--allo
>         SEQUENCER SUBCOMMANDS
>         ---------------------
>         include::sequencer.adoc[]
>       +
>       + ## Documentation/git-revert.adoc ##
>       +@@ Documentation/git-revert.adoc: include::rerere-options.adoc[]
>       + 	configuration variable can be used to enable this option by
>       + 	default.
>       +
>       ++include::rev-list-options.adoc[]
>       +
>       + SEQUENCER SUBCOMMANDS
>       + ---------------------
> 
> 
>   Documentation/git-cherry-pick.adoc | 2 ++
>   Documentation/git-revert.adoc      | 1 +
>   2 files changed, 3 insertions(+)
> 
> 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[]
> +
>   SEQUENCER SUBCOMMANDS
>   ---------------------
>   include::sequencer.adoc[]
> diff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc
> index ffba365e639..28827807473 100644
> --- a/Documentation/git-revert.adoc
> +++ b/Documentation/git-revert.adoc
> @@ -122,6 +122,7 @@ include::rerere-options.adoc[]
>   	configuration variable can be used to enable this option by
>   	default.
>   
> +include::rev-list-options.adoc[]
>   
>   SEQUENCER SUBCOMMANDS
>   ---------------------
> 
> base-commit: f814da676ae46aac5be0a98b99373a76dee6cedb