{"thread":{"id":"64043","subject":"[PATCH] cherry-pick: document rev-list options","startedAt":"2025-08-27T07:17:25Z","lastAt":"2025-08-27T16:14:28Z","messageCount":6,"participants":["Emily Shaffer via GitGitGadget","Andrew Jeffery","Phillip Wood","Emily Shaffer","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"525022","messageId":"pull.2042.git.git.1756279041881.gitgitgadget@gmail.com","threadId":"64043","inReplyTo":null,"subject":"[PATCH] cherry-pick: document rev-list options","fromName":"Emily Shaffer via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-27T07:17:21Z","receivedAt":"2025-08-27T07:17:25Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"From: Emily Shaffer <emilyshaffer@google.com>\n\nIn f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),\nwe added a handful of new options to `git cherry-pick`, but did not\ndocument them except by example. We have a nice shorthand for adding the\nrev-list documentation, so let's add it now.\n\nReported-by: Andrew Jeffrey <andrew@aj.id.au>\nSigned-off-by: Emily Shaffer <emilyshaffer@google.com>\n---\n    cherry-pick: document rev-list options\n    \n    Reported on socials (https://social.tchncs.de/@arj/115099134305875190).\n    rev-list-options.adoc is unfortunately pretty verbose, but I think it's\n    still better than having undocumented secret options. Or, worse, options\n    that are in examples but not anywhere else ;)\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2042%2Fnasamuffin%2Fcherry-pick-docs-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2042/nasamuffin/cherry-pick-docs-v1\nPull-Request: https://github.com/git/git/pull/2042\n\n Documentation/git-cherry-pick.adoc | 2 ++\n 1 file changed, 2 insertions(+)\n\ndiff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\nindex 42b41923d5f..03848aa9f21 100644\n--- a/Documentation/git-cherry-pick.adoc\n+++ b/Documentation/git-cherry-pick.adoc\n@@ -174,6 +174,8 @@ fail unless one of `--empty=keep` or `--allow-empty` are specified.\n \n include::rerere-options.adoc[]\n \n+include::rev-list-options.adoc[]\n+\n SEQUENCER SUBCOMMANDS\n ---------------------\n include::sequencer.adoc[]\n\nbase-commit: f814da676ae46aac5be0a98b99373a76dee6cedb\n-- \ngitgitgadget\n"},{"id":"525023","messageId":"pull.2042.v2.git.git.1756279345929.gitgitgadget@gmail.com","threadId":"64043","inReplyTo":"pull.2042.git.git.1756279041881.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: document rev-list opts in revert, cherry-pick","fromName":"Emily Shaffer via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-08-27T07:22:25Z","receivedAt":"2025-08-27T07:22:29Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"From: Emily Shaffer <emilyshaffer@google.com>\n\nIn f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),\nwe added a handful of new options to `git revert` and `git cherry-pick`,\nbut did not document them except by example to `cherry-pick` only. We\nhave a nice shorthand for adding the rev-list documentation, so let's\nadd it now, to both commands.\n\nReported-by: Andrew Jeffrey <andrew@aj.id.au>\nSigned-off-by: Emily Shaffer <emilyshaffer@google.com>\n---\n    cherry-pick: document rev-list options\n    \n    Ach, sorry for the noise, turns out it touched both revert and\n    cherry-pick, might as well do the docs for both.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2042%2Fnasamuffin%2Fcherry-pick-docs-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2042/nasamuffin/cherry-pick-docs-v2\nPull-Request: https://github.com/git/git/pull/2042\n\nRange-diff vs v1:\n\n 1:  fa352ccda08 ! 1:  f41cb4e8abc cherry-pick: document rev-list options\n     @@ Metadata\n      Author: Emily Shaffer <emilyshaffer@google.com>\n      \n       ## Commit message ##\n     -    cherry-pick: document rev-list options\n     +    doc: document rev-list opts in revert, cherry-pick\n      \n          In f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),\n     -    we added a handful of new options to `git cherry-pick`, but did not\n     -    document them except by example. We have a nice shorthand for adding the\n     -    rev-list documentation, so let's add it now.\n     +    we added a handful of new options to `git revert` and `git cherry-pick`,\n     +    but did not document them except by example to `cherry-pick` only. We\n     +    have a nice shorthand for adding the rev-list documentation, so let's\n     +    add it now, to both commands.\n      \n          Reported-by: Andrew Jeffrey <andrew@aj.id.au>\n          Signed-off-by: Emily Shaffer <emilyshaffer@google.com>\n     @@ Documentation/git-cherry-pick.adoc: fail unless one of `--empty=keep` or `--allo\n       SEQUENCER SUBCOMMANDS\n       ---------------------\n       include::sequencer.adoc[]\n     +\n     + ## Documentation/git-revert.adoc ##\n     +@@ Documentation/git-revert.adoc: include::rerere-options.adoc[]\n     + \tconfiguration variable can be used to enable this option by\n     + \tdefault.\n     + \n     ++include::rev-list-options.adoc[]\n     + \n     + SEQUENCER SUBCOMMANDS\n     + ---------------------\n\n\n Documentation/git-cherry-pick.adoc | 2 ++\n Documentation/git-revert.adoc      | 1 +\n 2 files changed, 3 insertions(+)\n\ndiff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\nindex 42b41923d5f..03848aa9f21 100644\n--- a/Documentation/git-cherry-pick.adoc\n+++ b/Documentation/git-cherry-pick.adoc\n@@ -174,6 +174,8 @@ fail unless one of `--empty=keep` or `--allow-empty` are specified.\n \n include::rerere-options.adoc[]\n \n+include::rev-list-options.adoc[]\n+\n SEQUENCER SUBCOMMANDS\n ---------------------\n include::sequencer.adoc[]\ndiff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc\nindex ffba365e639..28827807473 100644\n--- a/Documentation/git-revert.adoc\n+++ b/Documentation/git-revert.adoc\n@@ -122,6 +122,7 @@ include::rerere-options.adoc[]\n \tconfiguration variable can be used to enable this option by\n \tdefault.\n \n+include::rev-list-options.adoc[]\n \n SEQUENCER SUBCOMMANDS\n ---------------------\n\nbase-commit: f814da676ae46aac5be0a98b99373a76dee6cedb\n-- \ngitgitgadget\n"},{"id":"525024","messageId":"25c08035-8bb8-4a87-824c-76c88102a1ef@app.fastmail.com","threadId":"64043","inReplyTo":"pull.2042.v2.git.git.1756279345929.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: document rev-list opts in revert, cherry-pick","fromName":"Andrew Jeffery","fromEmail":"andrew@aj.id.au","sentAt":"2025-08-27T07:36:27Z","receivedAt":"2025-08-27T07:36:57Z","isPatch":true,"sender":{"key":"andrew@aj.id.au","avatar":null},"body":"\n\nOn Wed, 27 Aug 2025, at 16:52, Emily Shaffer via GitGitGadget wrote:\n> From: Emily Shaffer <emilyshaffer@google.com>\n>\n> In f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),\n> we added a handful of new options to `git revert` and `git cherry-pick`,\n> but did not document them except by example to `cherry-pick` only. We\n> have a nice shorthand for adding the rev-list documentation, so let's\n> add it now, to both commands.\n>\n> Reported-by: Andrew Jeffrey <andrew@aj.id.au>\n\nThanks!\n\nMy only input is my surname is spelled the surprising way: s/Jeffrey/Jeffery/ :) Hopefully someone can fix that up when applying it rather than needing a v3!\n\nAndrew\n"},{"id":"525029","messageId":"c856cecb-ab70-4c43-a952-cf0350c7949b@gmail.com","threadId":"64043","inReplyTo":"pull.2042.v2.git.git.1756279345929.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: document rev-list opts in revert, cherry-pick","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2025-08-27T09:41:55Z","receivedAt":"2025-08-27T09:41:59Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi Emily\n\nOn 27/08/2025 08:22, Emily Shaffer via GitGitGadget wrote:\n> From: Emily Shaffer <emilyshaffer@google.com>\n> \n> In f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),\n> we added a handful of new options to `git revert` and `git cherry-pick`,\n> but did not document them except by example to `cherry-pick` only. We\n> have a nice shorthand for adding the rev-list documentation, so let's\n> add it now, to both commands.\n\nI agree that it would be helpful to have a some rev-list options \nincluded here but this adds a huge amount of text to the man page which \ncomes before the documentation for frequently used options like \n\"--continue\". I'm not sure all of the new text is relevant to \ncherry-pick and revert. For instance do we need to document --bisect, \n-cherry-mark and --boundary here? I'm not sure the History \nSimplification and Commit Formatting sections are relevant either. There \nare already a bunch of ifdefs in rev-list-options.adoc that change \nwhat's included depending on which command we're documenting, maybe we \nshould add some more for the cherry-pick and revert documentation?\n\nThanks\n\nPhillip> Reported-by: Andrew Jeffrey <andrew@aj.id.au>\n> Signed-off-by: Emily Shaffer <emilyshaffer@google.com>\n> ---\n>      cherry-pick: document rev-list options\n>      \n>      Ach, sorry for the noise, turns out it touched both revert and\n>      cherry-pick, might as well do the docs for both.\n> \n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2042%2Fnasamuffin%2Fcherry-pick-docs-v2\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2042/nasamuffin/cherry-pick-docs-v2\n> Pull-Request: https://github.com/git/git/pull/2042\n> \n> Range-diff vs v1:\n> \n>   1:  fa352ccda08 ! 1:  f41cb4e8abc cherry-pick: document rev-list options\n>       @@ Metadata\n>        Author: Emily Shaffer <emilyshaffer@google.com>\n>        \n>         ## Commit message ##\n>       -    cherry-pick: document rev-list options\n>       +    doc: document rev-list opts in revert, cherry-pick\n>        \n>            In f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),\n>       -    we added a handful of new options to `git cherry-pick`, but did not\n>       -    document them except by example. We have a nice shorthand for adding the\n>       -    rev-list documentation, so let's add it now.\n>       +    we added a handful of new options to `git revert` and `git cherry-pick`,\n>       +    but did not document them except by example to `cherry-pick` only. We\n>       +    have a nice shorthand for adding the rev-list documentation, so let's\n>       +    add it now, to both commands.\n>        \n>            Reported-by: Andrew Jeffrey <andrew@aj.id.au>\n>            Signed-off-by: Emily Shaffer <emilyshaffer@google.com>\n>       @@ Documentation/git-cherry-pick.adoc: fail unless one of `--empty=keep` or `--allo\n>         SEQUENCER SUBCOMMANDS\n>         ---------------------\n>         include::sequencer.adoc[]\n>       +\n>       + ## Documentation/git-revert.adoc ##\n>       +@@ Documentation/git-revert.adoc: include::rerere-options.adoc[]\n>       + \tconfiguration variable can be used to enable this option by\n>       + \tdefault.\n>       +\n>       ++include::rev-list-options.adoc[]\n>       +\n>       + SEQUENCER SUBCOMMANDS\n>       + ---------------------\n> \n> \n>   Documentation/git-cherry-pick.adoc | 2 ++\n>   Documentation/git-revert.adoc      | 1 +\n>   2 files changed, 3 insertions(+)\n> \n> diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\n> index 42b41923d5f..03848aa9f21 100644\n> --- a/Documentation/git-cherry-pick.adoc\n> +++ b/Documentation/git-cherry-pick.adoc\n> @@ -174,6 +174,8 @@ fail unless one of `--empty=keep` or `--allow-empty` are specified.\n>   \n>   include::rerere-options.adoc[]\n>   \n> +include::rev-list-options.adoc[]\n> +\n>   SEQUENCER SUBCOMMANDS\n>   ---------------------\n>   include::sequencer.adoc[]\n> diff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc\n> index ffba365e639..28827807473 100644\n> --- a/Documentation/git-revert.adoc\n> +++ b/Documentation/git-revert.adoc\n> @@ -122,6 +122,7 @@ include::rerere-options.adoc[]\n>   \tconfiguration variable can be used to enable this option by\n>   \tdefault.\n>   \n> +include::rev-list-options.adoc[]\n>   \n>   SEQUENCER SUBCOMMANDS\n>   ---------------------\n> \n> base-commit: f814da676ae46aac5be0a98b99373a76dee6cedb\n\n"},{"id":"525032","messageId":"CAJoAoZmEX8_cOGByD1sfRimNxkuY8Dqq9x3XvQ3SuoLD8aO79Q@mail.gmail.com","threadId":"64043","inReplyTo":"c856cecb-ab70-4c43-a952-cf0350c7949b@gmail.com","subject":"Re: [PATCH v2] doc: document rev-list opts in revert, cherry-pick","fromName":"Emily Shaffer","fromEmail":"nasamuffin@google.com","sentAt":"2025-08-27T11:34:31Z","receivedAt":"2025-08-27T11:34:47Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Wed, Aug 27, 2025 at 11:41 AM Phillip Wood <phillip.wood123@gmail.com> wrote:\n>\n> Hi Emily\n>\n> On 27/08/2025 08:22, Emily Shaffer via GitGitGadget wrote:\n> > From: Emily Shaffer <emilyshaffer@google.com>\n> >\n> > In f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),\n> > we added a handful of new options to `git revert` and `git cherry-pick`,\n> > but did not document them except by example to `cherry-pick` only. We\n> > have a nice shorthand for adding the rev-list documentation, so let's\n> > add it now, to both commands.\n>\n> I agree that it would be helpful to have a some rev-list options\n> included here but this adds a huge amount of text to the man page which\n> comes before the documentation for frequently used options like\n> \"--continue\". I'm not sure all of the new text is relevant to\n> cherry-pick and revert. For instance do we need to document --bisect,\n> -cherry-mark and --boundary here? I'm not sure the History\n> Simplification and Commit Formatting sections are relevant either. There\n> are already a bunch of ifdefs in rev-list-options.adoc that change\n> what's included depending on which command we're documenting, maybe we\n> should add some more for the cherry-pick and revert documentation?\n\nI thought too that the rev-list-options.adoc is probably longer than\nit needs to be for most of the places where we include it. I wonder if\nit's worth breaking that inclusion into smaller, more relevant parts?\n\nFull disclosure, if that's the solution we want to go with, it will\ntake much longer for me to address it than for someone else to,\nalthough I'm interested.\n\n - Emily\n\n>\n> Thanks\n>\n> Phillip> Reported-by: Andrew Jeffrey <andrew@aj.id.au>\n> > Signed-off-by: Emily Shaffer <emilyshaffer@google.com>\n> > ---\n> >      cherry-pick: document rev-list options\n> >\n> >      Ach, sorry for the noise, turns out it touched both revert and\n> >      cherry-pick, might as well do the docs for both.\n> >\n> > Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2042%2Fnasamuffin%2Fcherry-pick-docs-v2\n> > Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2042/nasamuffin/cherry-pick-docs-v2\n> > Pull-Request: https://github.com/git/git/pull/2042\n> >\n> > Range-diff vs v1:\n> >\n> >   1:  fa352ccda08 ! 1:  f41cb4e8abc cherry-pick: document rev-list options\n> >       @@ Metadata\n> >        Author: Emily Shaffer <emilyshaffer@google.com>\n> >\n> >         ## Commit message ##\n> >       -    cherry-pick: document rev-list options\n> >       +    doc: document rev-list opts in revert, cherry-pick\n> >\n> >            In f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),\n> >       -    we added a handful of new options to `git cherry-pick`, but did not\n> >       -    document them except by example. We have a nice shorthand for adding the\n> >       -    rev-list documentation, so let's add it now.\n> >       +    we added a handful of new options to `git revert` and `git cherry-pick`,\n> >       +    but did not document them except by example to `cherry-pick` only. We\n> >       +    have a nice shorthand for adding the rev-list documentation, so let's\n> >       +    add it now, to both commands.\n> >\n> >            Reported-by: Andrew Jeffrey <andrew@aj.id.au>\n> >            Signed-off-by: Emily Shaffer <emilyshaffer@google.com>\n> >       @@ Documentation/git-cherry-pick.adoc: fail unless one of `--empty=keep` or `--allo\n> >         SEQUENCER SUBCOMMANDS\n> >         ---------------------\n> >         include::sequencer.adoc[]\n> >       +\n> >       + ## Documentation/git-revert.adoc ##\n> >       +@@ Documentation/git-revert.adoc: include::rerere-options.adoc[]\n> >       +       configuration variable can be used to enable this option by\n> >       +       default.\n> >       +\n> >       ++include::rev-list-options.adoc[]\n> >       +\n> >       + SEQUENCER SUBCOMMANDS\n> >       + ---------------------\n> >\n> >\n> >   Documentation/git-cherry-pick.adoc | 2 ++\n> >   Documentation/git-revert.adoc      | 1 +\n> >   2 files changed, 3 insertions(+)\n> >\n> > diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\n> > index 42b41923d5f..03848aa9f21 100644\n> > --- a/Documentation/git-cherry-pick.adoc\n> > +++ b/Documentation/git-cherry-pick.adoc\n> > @@ -174,6 +174,8 @@ fail unless one of `--empty=keep` or `--allow-empty` are specified.\n> >\n> >   include::rerere-options.adoc[]\n> >\n> > +include::rev-list-options.adoc[]\n> > +\n> >   SEQUENCER SUBCOMMANDS\n> >   ---------------------\n> >   include::sequencer.adoc[]\n> > diff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc\n> > index ffba365e639..28827807473 100644\n> > --- a/Documentation/git-revert.adoc\n> > +++ b/Documentation/git-revert.adoc\n> > @@ -122,6 +122,7 @@ include::rerere-options.adoc[]\n> >       configuration variable can be used to enable this option by\n> >       default.\n> >\n> > +include::rev-list-options.adoc[]\n> >\n> >   SEQUENCER SUBCOMMANDS\n> >   ---------------------\n> >\n> > base-commit: f814da676ae46aac5be0a98b99373a76dee6cedb\n>\n"},{"id":"525051","messageId":"xmqqjz2o3foe.fsf@gitster.g","threadId":"64043","inReplyTo":"pull.2042.v2.git.git.1756279345929.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: document rev-list opts in revert, cherry-pick","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-27T16:14:25Z","receivedAt":"2025-08-27T16:14:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Emily Shaffer via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Emily Shaffer <emilyshaffer@google.com>\n>\n> In f873a273d1 (revert: accept arbitrary rev-list options, 2010-06-14),\n> we added a handful of new options to `git revert` and `git cherry-pick`,\n> but did not document them except by example to `cherry-pick` only. We\n> have a nice shorthand for adding the rev-list documentation, so let's\n> add it now, to both commands.\n\nThat's a blast from the past.\n\n> diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc\n> index 42b41923d5f..03848aa9f21 100644\n> --- a/Documentation/git-cherry-pick.adoc\n> +++ b/Documentation/git-cherry-pick.adoc\n> @@ -174,6 +174,8 @@ fail unless one of `--empty=keep` or `--allow-empty` are specified.\n>  \n>  include::rerere-options.adoc[]\n>  \n> +include::rev-list-options.adoc[]\n> +\n\nAre there options that rev-list family of commands take that are\nnonsense in the context of cherry-pick (and revert)?\n\nThe rev-list-options.adoc[] file is designed to be included from\ndifferent places, so for example it omits certain things from\nappearing in the output.  E.g., by doing things like:\n\n    `--ignore-missing`::\n            Upon seeing an invalid object name in the input, pretend as if\n            the bad input was not given.\n\n    ifndef::git-rev-list[]\n    `--bisect`::\n            Pretend as if the bad bisection ref `refs/bisect/bad`\n            was listed and as if it was followed by `--not` and the good\n            bisection refs `refs/bisect/good-*` on the command\n            line.\n    endif::git-rev-list[]\n\nand not doing\n\n    :git-rev-list: 1\n    include::rev-list-options.adoc[]\n\nwe can exclude specific parts of the rev-list-options.adoc from\ninclusion.\n\nI know that the implementation took a blind^Wstupid route to allow\neverything, but documenting them for unsuspecting general public\nwould make the harm larger.  They wouldn't have even imagined to\ntype\n\n    git cherry-pick --graph master\n\nif they weren't told that the command took such a nonsense option.\nHave you reviewed what is in rev-list-options.adoc and thought about\nexcluding certain parts when the file is included in either\ngit-cherry-pick.adoc or git-revert.adoc?\n"}]}