{"thread":{"id":"60598","subject":"[BUG] git-bisect man page description of terms command doesn't mention old/new support","startedAt":"2023-12-09T11:58:51Z","lastAt":"2024-02-09T09:39:21Z","messageCount":11,"participants":["Britton Kerin","Junio C Hamano","Matthieu Moy","Kristoffer Haugsbakk","Jean-Noël Avila","Christian Couder"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"485502","messageId":"CAC4O8c9ieZC4SBJf54ZuTfAvnkhGuDaibBQ-m9Zw_n5VhUFPag@mail.gmail.com","threadId":"60598","inReplyTo":null,"subject":"[BUG] git-bisect man page description of terms command doesn't mention old/new support","fromName":"Britton Kerin","fromEmail":"britton.kerin@gmail.com","sentAt":"2023-12-09T11:58:37Z","receivedAt":"2023-12-09T11:58:51Z","isPatch":false,"sender":{"key":"britton.kerin@gmail.com","avatar":"https://avatars.githubusercontent.com/u/7434164?v=4"},"body":"It's a very small issue but it seems that git bisect terms does\nsupport --term-old and --term-new options, however the man page says:\n\n git bisect terms [--term-good | --term-bad]\n\nThe description for the start subcommand does document the support for\nthe more general terms correctly:\n\n git bisect start [--term-{new,bad}= --term-{old,good}=]\n\nso maybe it's worth fixing the git bisect terms documentation.\n\nBritton\n"},{"id":"485504","messageId":"xmqqzfyjmk02.fsf@gitster.g","threadId":"60598","inReplyTo":"CAC4O8c9ieZC4SBJf54ZuTfAvnkhGuDaibBQ-m9Zw_n5VhUFPag@mail.gmail.com","subject":"Re* [BUG] git-bisect man page description of terms command doesn't mention old/new support","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-09T16:13:49Z","receivedAt":"2023-12-09T16:13:52Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Britton Kerin writes:\n\n> It's a very small issue but it seems that git bisect terms does\n> support --term-old and --term-new options, however the man page says:\n>\n> git bisect terms [--term-good | --term-bad]\n>\n> The description for the start subcommand does document the support for\n> the more general terms correctly:\n>\n> git bisect start [--term-{new,bad}= --term-{old,good}=]\n>\n> so maybe it's worth fixing the git bisect terms documentation.\n\nIn the description, we see\n\n To get a reminder of the currently used terms, use\n\n ------------------------------------------------\n git bisect terms\n ------------------------------------------------\n\n You can get just the old (respectively new) term with `git bisect terms\n --term-old` or `git bisect terms --term-good`.\n\nso you could read that\n\n\tgit bisect terms --term-good\n\tgit bisect terms --term-old\n\nare the same thing, and when you squint your eyes, you can probably\nguess that\n\n\tgit bisect terms --term-bad\n\tgit bisect terms --term-new\n\nare the same. But I agree that the documentation should not force\nyou to guess. This dates back to 21b55e33 (bisect: add 'git bisect\nterms' to view the current terms, 2015-06-29).\n\n------------ >8 ------------ >8 ------------ >8 ------------\nSubject: [PATCH] bisect: document \"terms\" subcommand more fully\n\nThe documentation for \"git bisect terms\", although it did not hide\nany information, was a bit incomplete and forced readers to fill in\nthe blanks to get the complete picture.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-bisect.txt | 8 +++++---\n 1 file changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git c/Documentation/git-bisect.txt w/Documentation/git-bisect.txt\nindex 191b4a42b6..16daa09c78 100644\n--- c/Documentation/git-bisect.txt\n+++ w/Documentation/git-bisect.txt\n@@ -20,7 +20,7 @@ on the subcommand:\n \t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n git bisect (bad|new|) []\n git bisect (good|old|) [...]\n- git bisect terms [--term-good | --term-bad]\n+ git bisect terms [--term-(good|old) | --term-(bad|new)]\n git bisect skip [(|)...]\n git bisect reset []\n git bisect (visualize|view)\n@@ -165,8 +165,10 @@ To get a reminder of the currently used terms, use\n git bisect terms\n ------------------------------------------------\n \n-You can get just the old (respectively new) term with `git bisect terms\n---term-old` or `git bisect terms --term-good`.\n+You can get just the old term with `git bisect terms --term-old`\n+or `git bisect terms --term-good`; `git bisect terms --term-new`\n+and `git bisect terms --term-bad` can be used to learn how to call\n+the commits more recent than the sought change.\n \n If you would like to use your own terms instead of \"bad\"/\"good\" or\n \"new\"/\"old\", you can choose any names you like (except existing bisect\n\n"},{"id":"485536","messageId":"24a42fa6-7bc4-4a3b-8bf4-a0ef85dc457a@matthieu-moy.fr","threadId":"60598","inReplyTo":"xmqqzfyjmk02.fsf@gitster.g","subject":"Re: Re* [BUG] git-bisect man page description of terms command doesn't mention old/new support","fromName":"Matthieu Moy","fromEmail":"git@matthieu-moy.fr","sentAt":"2023-12-11T12:34:05Z","receivedAt":"2023-12-11T12:58:21Z","isPatch":false,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"On 12/9/23 17:13, Junio C Hamano wrote:\n\n> so you could read that\n> \n> \tgit bisect terms --term-good\n> \tgit bisect terms --term-old\n> \n> are the same thing, and when you squint your eyes, you can probably\n> guess that\n> \n> \tgit bisect terms --term-bad\n> \tgit bisect terms --term-new\n> \n> are the same. But I agree that the documentation should not force\n> you to guess.\n\nAgreed.\n> --- c/Documentation/git-bisect.txt\n> +++ w/Documentation/git-bisect.txt\n> @@ -20,7 +20,7 @@ on the subcommand:\n> \t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n> git bisect (bad|new|) []\n> git bisect (good|old|) [...]\n> - git bisect terms [--term-good | --term-bad]\n> + git bisect terms [--term-(good|old) | --term-(bad|new)]\n\nNit: just above we have the description for `bisect start` saying:\n\n--term-{new,bad}= --term-{old,good}=\n\nit probably makes sense to make both homogeneous (start with the same \nalternative, and make the {...,...} vs (...|...) notations consistent. \nThe (...|...) notation seems the most common).\n\nIn any case, the patch looks good to me, thanks.\n\n-- \nMatthieu Moy\nhttps://matthieu-moy.fr/\n"},{"id":"485538","messageId":"xmqqil54vkya.fsf@gitster.g","threadId":"60598","inReplyTo":"24a42fa6-7bc4-4a3b-8bf4-a0ef85dc457a@matthieu-moy.fr","subject":"Re: Re* [BUG] git-bisect man page description of terms command doesn't mention old/new support","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-11T15:05:17Z","receivedAt":"2023-12-11T15:05:24Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Nit: just above we have the description for `bisect start` saying:\n>\n> --term-{new,bad}= --term-{old,good}=\n>\n> it probably makes sense to make both homogeneous (start with the same\n> alternative, and make the {...,...} vs (...|...) notations\n> consistent. The (...|...) notation seems the most common).\n\nThanks for noticing; I think it has already been fixed a few months\nago, but apparently what I sent predates 3f02785d (doc/git-bisect:\nclarify `git bisect run` syntax, 2023-10-23). So when the patch\ngets merged, it will fix itself ;-)\n\n> In any case, the patch looks good to me, thanks.\n\nThanks.\n"},{"id":"488184","messageId":"20240207214436.538586-1-gitster@pobox.com","threadId":"60598","inReplyTo":"24a42fa6-7bc4-4a3b-8bf4-a0ef85dc457a@matthieu-moy.fr","subject":"[PATCH 0/2] minute \"git bisect\" doc updates","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-07T21:44:34Z","receivedAt":"2024-02-07T21:44:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"git bisect\" documentation was a bit sketchy on alternative keywords\n\"new\" and \"old\", that are used to signal if a command is from the\npart of the history that is newer or older than \"a significant\nevent\" the bisection is trying to find. Here are two small patches\nthat improves the documentation.\n\nI am trying to flush my \"stalled topics\" queue. Here is a small and\n(hopefully) easy-to-finish one.\n\nThe original discussion was from early December 2023 and can be\nfound at\n\nhttps://lore.kernel.org/git/CAC4O8c9ieZC4SBJf54ZuTfAvnkhGuDaibBQ-m9Zw_n5VhUFPag@mail.gmail.com/\n\n\n\nJunio C Hamano (2):\n bisect: document \"terms\" subcommand more fully\n bisect: document command line arguments for \"bisect start\"\n\n Documentation/git-bisect.txt | 10 ++++++----\n 1 file changed, 6 insertions(+), 4 deletions(-)\n\n-- \n2.43.0-561-g235986be82\n\n"},{"id":"488185","messageId":"20240207214436.538586-2-gitster@pobox.com","threadId":"60598","inReplyTo":"20240207214436.538586-1-gitster@pobox.com","subject":"[PATCH 1/2] bisect: document \"terms\" subcommand more fully","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-07T21:44:35Z","receivedAt":"2024-02-07T21:44:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The documentation for \"git bisect terms\", although it did not hide\nany information, was a bit incomplete and forced readers to fill in\nthe blanks to get the complete picture.\n\nAcked-by: Matthieu Moy \nSigned-off-by: Junio C Hamano \n---\n Documentation/git-bisect.txt | 8 +++++---\n 1 file changed, 5 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex fbb39fbdf5..3d813f9c77 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -20,7 +20,7 @@ on the subcommand:\n \t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n git bisect (bad|new|) []\n git bisect (good|old|) [...]\n- git bisect terms [--term-good | --term-bad]\n+ git bisect terms [--term-(good|old) | --term-(bad|new)]\n git bisect skip [(|)...]\n git bisect reset []\n git bisect (visualize|view)\n@@ -165,8 +165,10 @@ To get a reminder of the currently used terms, use\n git bisect terms\n ------------------------------------------------\n \n-You can get just the old (respectively new) term with `git bisect terms\n---term-old` or `git bisect terms --term-good`.\n+You can get just the old term with `git bisect terms --term-old`\n+or `git bisect terms --term-good`; `git bisect terms --term-new`\n+and `git bisect terms --term-bad` can be used to learn how to call\n+the commits more recent than the sought change.\n \n If you would like to use your own terms instead of \"bad\"/\"good\" or\n \"new\"/\"old\", you can choose any names you like (except existing bisect\n-- \n2.43.0-561-g235986be82\n\n"},{"id":"488186","messageId":"20240207214436.538586-3-gitster@pobox.com","threadId":"60598","inReplyTo":"20240207214436.538586-1-gitster@pobox.com","subject":"[PATCH 2/2] bisect: document command line arguments for \"bisect start\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-07T21:44:36Z","receivedAt":"2024-02-07T21:44:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The syntax commonly used for alternatives is --opt-(a|b), not\n--opt-{a,b}.\n\nList bad/new and good/old consistently in this order, to be\nconsistent with the description for \"git bisect terms\". Clarify\n to either or to make them consistent\nwith the description of \"git bisect (good|bad)\" subcommands.\n\nSuggested-by: Matthieu Moy \nSigned-off-by: Junio C Hamano \n---\n Documentation/git-bisect.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex 3d813f9c77..73f889b97b 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -16,7 +16,7 @@ DESCRIPTION\n The command takes various subcommands, and different options depending\n on the subcommand:\n \n- git bisect start [--term-{new,bad}= --term-{old,good}=]\n+ git bisect start [--term-(bad|new)= --term-(good|old)=]\n \t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n git bisect (bad|new|) []\n git bisect (good|old|) [...]\n-- \n2.43.0-561-g235986be82\n\n"},{"id":"488211","messageId":"a8e67945-153b-43bb-b1b0-ea24fa786097@app.fastmail.com","threadId":"60598","inReplyTo":"20240207214436.538586-2-gitster@pobox.com","subject":"Re: [PATCH 1/2] bisect: document \"terms\" subcommand more fully","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2024-02-08T06:36:55Z","receivedAt":"2024-02-08T06:37:40Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Wed, Feb 7, 2024, at 22:44, Junio C Hamano wrote:\n> The documentation for \"git bisect terms\", although it did not hide\n> any information, was a bit incomplete and forced readers to fill in\n> the blanks to get the complete picture.\n>\n> Acked-by: Matthieu Moy \n> Signed-off-by: Junio C Hamano \n> ---\n\nPast tense? How about:\n\n The documentation for \"git bisect terms\"---although it does not hide\n any information---is a bit incomplete and forces readers to fill in\n the blanks to get the complete picture.\n\n-- \nKristoffer Haugsbakk\n\n"},{"id":"488234","messageId":"21ec33d4-4036-4763-9117-fbbdca1e2273@gmail.com","threadId":"60598","inReplyTo":"20240207214436.538586-3-gitster@pobox.com","subject":"Re: [PATCH 2/2] bisect: document command line arguments for \"bisect start\"","fromName":"Jean-Noël Avila","fromEmail":"avila.jn@gmail.com","sentAt":"2024-02-08T16:18:54Z","receivedAt":"2024-02-08T16:18:58Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 07/02/2024 à 22:44, Junio C Hamano a écrit :\n> The syntax commonly used for alternatives is --opt-(a|b), not\n> --opt-{a,b}.\n>\n> List bad/new and good/old consistently in this order, to be\n> consistent with the description for \"git bisect terms\". Clarify\n> to either or to make them consistent\n> with the description of \"git bisect (good|bad)\" subcommands.\n>\n> Suggested-by: Matthieu Moy \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/git-bisect.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\n> index 3d813f9c77..73f889b97b 100644\n> --- a/Documentation/git-bisect.txt\n> +++ b/Documentation/git-bisect.txt\n> @@ -16,7 +16,7 @@ DESCRIPTION\n> The command takes various subcommands, and different options depending\n> on the subcommand:\n> \n> - git bisect start [--term-{new,bad}= --term-{old,good}=]\n> + git bisect start [--term-(bad|new)= --term-(good|old)=]\n> \t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n> git bisect (bad|new|) []\n> git bisect (good|old|) [...]\n\n\nLGTM\n\n"},{"id":"488236","messageId":"xmqqil2yq4vr.fsf@gitster.g","threadId":"60598","inReplyTo":"a8e67945-153b-43bb-b1b0-ea24fa786097@app.fastmail.com","subject":"Re: [PATCH 1/2] bisect: document \"terms\" subcommand more fully","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-08T16:48:08Z","receivedAt":"2024-02-08T16:48:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Wed, Feb 7, 2024, at 22:44, Junio C Hamano wrote:\n>> The documentation for \"git bisect terms\", although it did not hide\n>> any information, was a bit incomplete and forced readers to fill in\n>> the blanks to get the complete picture.\n>>\n>> Acked-by: Matthieu Moy \n>> Signed-off-by: Junio C Hamano \n>> ---\n>\n> Past tense? How about:\n>\n> The documentation for \"git bisect terms\"---although it does not hide\n> any information---is a bit incomplete and forces readers to fill in\n> the blanks to get the complete picture.\n\nRight.\nThanks.\n"},{"id":"488284","messageId":"CAP8UFD0eNvMrUDshZBfrE+3WbRWGr6oa-o8Q4ecrLcY1-vhyFQ@mail.gmail.com","threadId":"60598","inReplyTo":"20240207214436.538586-1-gitster@pobox.com","subject":"Re: [PATCH 0/2] minute \"git bisect\" doc updates","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2024-02-09T09:39:08Z","receivedAt":"2024-02-09T09:39:21Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Wed, Feb 7, 2024 at 11:13 PM Junio C Hamano wrote:\n>\n> \"git bisect\" documentation was a bit sketchy on alternative keywords\n> \"new\" and \"old\", that are used to signal if a command is from the\n> part of the history that is newer or older than \"a significant\n> event\" the bisection is trying to find. Here are two small patches\n> that improves the documentation.\n>\n> I am trying to flush my \"stalled topics\" queue. Here is a small and\n> (hopefully) easy-to-finish one.\n>\n> The original discussion was from early December 2023 and can be\n> found at\n>\n> https://lore.kernel.org/git/CAC4O8c9ieZC4SBJf54ZuTfAvnkhGuDaibBQ-m9Zw_n5VhUFPag@mail.gmail.com/\n>\n> Junio C Hamano (2):\n> bisect: document \"terms\" subcommand more fully\n> bisect: document command line arguments for \"bisect start\"\n\nBoth patches look good to me. You can add my \"Reviewed-by:\".\n\nThanks!\n"}]}