From: Phillip Wood <phillip.wood123@gmail•com>
To: Emily Shaffer via GitGitGadget <gitgitgadget@gmail•com>,
git@vger•kernel.org
Cc: Andrew Jeffrey <andrew@aj•id.au>,
Emily Shaffer <emilyshaffer@google•com>
Subject: Re: [PATCH v2] doc: document rev-list opts in revert, cherry-pick
Date: Wed, 27 Aug 2025 10:41:55 +0100 [thread overview]
Message-ID: <c856cecb-ab70-4c43-a952-cf0350c7949b@gmail.com> (raw)
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:
> 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>
> 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
next prev parent reply other threads:[~2025-08-27 9:41 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-08-27 7:17 [PATCH] cherry-pick: document rev-list options Emily Shaffer via GitGitGadget
2025-08-27 7:22 ` [PATCH v2] doc: document rev-list opts in revert, cherry-pick Emily Shaffer via GitGitGadget
2025-08-27 7:36 ` Andrew Jeffery
2025-08-27 9:41 ` Phillip Wood [this message]
2025-08-27 11:34 ` Emily Shaffer
2025-08-27 16:14 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=c856cecb-ab70-4c43-a952-cf0350c7949b@gmail.com \
--to=phillip.wood123@gmail$(echo .)com \
--cc=andrew@aj$(echo .)id.au \
--cc=emilyshaffer@google$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=phillip.wood@dunelm$(echo .)org.uk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox