cherry-pick: document rev-list options
PATCH 1/1 cherry-pick: document rev-list options
From: Emily Shaffer <[email protected]>
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.
---
cherry-pick: document rev-list options
Reported on socials (https://social.tchncs.de/@arj/115099134305875190).
rev-list-options.adoc is unfortunately pretty verbose, but I think it's still better than having undocumented secret options. Or, worse, options that are in examples but not anywhere else ;)
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2042%2Fnasamuffin%2Fcherry-pick-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2042/nasamuffin/cherry-pick-docs-v1
Pull-Request: https://github.com/git/git/pull/2042
Documentation/git-cherry-pick.adoc | 2 ++ 1 file changed, 2 insertions(+)
Documentation/git-cherry-pick.adoc +2 -0
@@ -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[]
base-commit: f814da676ae46aac5be0a98b99373a76dee6cedb
Signature · 1 line
gitgitgadget
PATCH v2 1/1 doc: document rev-list opts in revert, cherry-pick
From: Emily Shaffer <[email protected]>
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.
---
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 <[email protected]>
## 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.
@@ 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(+)
Documentation/git-cherry-pick.adoc +2 -0
@@ -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[]
Documentation/git-revert.adoc +1 -0
@@ -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
Signature · 1 line
gitgitgadget
Re: [PATCH v2] doc: document rev-list opts in revert, cherry-pick
Quoted 9 lines · Emily Shaffer via GitGitGadget
From: Emily Shaffer <[email protected]>
In
f873a273d1(revert: accept arbitrary rev-list options, 2010-06-14), we added a handful of new options togit revertandgit cherry-pick, but did not document them except by example tocherry-pickonly. We have a nice shorthand for adding the rev-list documentation, so let's add it now, to both commands.Reported-by Andrew Jeffrey <[email protected]>
Thanks!
My 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!
Andrew
Re: [PATCH v2] doc: document rev-list opts in revert, cherry-pick
In reply to Emily Shaffer via GitGitGadgetHi Emily
Quoted 7 lines · Emily Shaffer via GitGitGadget
From: Emily Shaffer <[email protected]>
In
f873a273d1(revert: accept arbitrary rev-list options, 2010-06-14), we added a handful of new options togit revertandgit cherry-pick, but did not document them except by example tocherry-pickonly. 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 <[email protected]>
Quoted 79 lines
Signed-off-by Emily Shaffer <[email protected]>---
cherry-pick: document rev-list optionsAch, 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/2042Range-diff vs v1:
1:
fa352ccda08! 1:f41cb4e8abccherry-pick: document rev-list options
@@ Metadata
Author: Emily Shaffer <[email protected]>## Commit message ##
- cherry-pick: document rev-list options
+ doc: document rev-list opts in revert, cherry-pickIn
f873a273d1(revert: accept arbitrary rev-list options, 2010-06-14),
- we added a handful of new options togit 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 togit revertandgit cherry-pick,
+ but did not document them except by example tocherry-pickonly. We
+ have a nice shorthand for adding the rev-list documentation, so let's
+ add it now, to both commands.Reported-by Andrew Jeffrey <[email protected]>Signed-off-by Emily Shaffer <[email protected]>@@
Documentation/git-cherry-pick.adoc: fail unless one of--empty=keepor `--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(+)Documentation/git-cherry-pick.adoc +2
-0@@ -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[]Documentation/git-revert.adoc +1
-0@@ -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
Re: [PATCH v2] doc: document rev-list opts in revert, cherry-pick
Quoted 12 lines · Phillip Wood
Hi Emily
Quoted 7 lines · Emily Shaffer via GitGitGadget
From: Emily Shaffer <[email protected]>
In
f873a273d1(revert: accept arbitrary rev-list options, 2010-06-14), we added a handful of new options togit revertandgit cherry-pick, but did not document them except by example tocherry-pickonly. We have a nice shorthand for adding the rev-list documentation, so let's add it now, to both commands.
Quoted 10 lines
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?
I thought too that the rev-list-options.adoc is probably longer than it needs to be for most of the places where we include it. I wonder if it's worth breaking that inclusion into smaller, more relevant parts?
Full disclosure, if that's the solution we want to go with, it will take much longer for me to address it than for someone else to, although I'm interested.
- Emily
Quoted 84 lines
Thanks
Phillip> Reported-by: Andrew Jeffrey <[email protected]>
Quoted 79 lines
Signed-off-by Emily Shaffer <[email protected]>---
cherry-pick: document rev-list optionsAch, 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/2042Range-diff vs v1:
1:
fa352ccda08! 1:f41cb4e8abccherry-pick: document rev-list options
@@ Metadata
Author: Emily Shaffer <[email protected]>## Commit message ##
- cherry-pick: document rev-list options
+ doc: document rev-list opts in revert, cherry-pickIn
f873a273d1(revert: accept arbitrary rev-list options, 2010-06-14),
- we added a handful of new options togit 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 togit revertandgit cherry-pick,
+ but did not document them except by example tocherry-pickonly. We
+ have a nice shorthand for adding the rev-list documentation, so let's
+ add it now, to both commands.Reported-by Andrew Jeffrey <[email protected]>Signed-off-by Emily Shaffer <[email protected]>@@
Documentation/git-cherry-pick.adoc: fail unless one of--empty=keepor `--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(+)Documentation/git-cherry-pick.adoc +2
-0@@ -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[]Documentation/git-revert.adoc +1
-0@@ -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
Re: [PATCH v2] doc: document rev-list opts in revert, cherry-pick
In reply to Emily Shaffer via GitGitGadgetQuoted 7 lines · Emily Shaffer via GitGitGadget
From: Emily Shaffer <[email protected]>
In
f873a273d1(revert: accept arbitrary rev-list options, 2010-06-14), we added a handful of new options togit revertandgit cherry-pick, but did not document them except by example tocherry-pickonly. 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.
Documentation/git-cherry-pick.adoc fail unless one of `--empty=keep` or `--allow-empty` are specified. · line 178
Quoted 10 lines
Documentation/git-cherry-pick.adoc +2
-0@@ -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?