{"thread":{"id":"60413","subject":"[PATCH] doc/git-bisect: clarify `git bisect run` syntax","startedAt":"2023-10-22T20:02:53Z","lastAt":"2023-10-24T00:12:14Z","messageCount":12,"participants":["cousteau via GitGitGadget","Eric Sunshine","Junio C Hamano","Patrick Steinhardt","Javier Mora"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"483637","messageId":"pull.1602.git.1698004968582.gitgitgadget@gmail.com","threadId":"60413","inReplyTo":null,"subject":"[PATCH] doc/git-bisect: clarify `git bisect run` syntax","fromName":"cousteau via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-10-22T20:02:48Z","receivedAt":"2023-10-22T20:02:53Z","isPatch":true,"sender":{"key":"name:cousteau","avatar":null},"body":"From: Javier Mora \n\nThe description of the `git bisect run` command syntax at the beginning\nof the manpage is `git bisect run ...`, which isn't quite clear\nabout what `` is or what the `...` mean; one could think that it is\nthe whole (quoted) command line with all arguments in a single string,\nor that it supports multiple commands, or that it doesn't accept\ncommands with arguments at all.\n\nChange to `git bisect run [...]` to clarify the syntax.\n\nSigned-off-by: Javier Mora \n---\n doc/git-bisect: clarify git bisect run syntax\n \n I saw someone in IRC wondering about the syntax for git bisect run for a\n command with arguments, and found that its short description at the\n beginning of the manpage is not very clear (although it gets clarified\n later when it is properly described). It describes the syntax as git\n bisect run ... which is a bit confusing; it should say git bisect\n run [...], otherwise it somehow looks like you have to \"enter\n one or more commands\", and that each command is a single argument.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1602%2Fcousteaulecommandant%2Fman-git-bisect-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1602/cousteaulecommandant/man-git-bisect-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1602\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 7872dba3aef..19bbed49238 100644\n--- a/Documentation/git-bisect.txt\n+++ b/Documentation/git-bisect.txt\n@@ -26,7 +26,7 @@ on the subcommand:\n git bisect (visualize|view)\n git bisect replay \n git bisect log\n- git bisect run ...\n+ git bisect run [...]\n git bisect help\n \n This command uses a binary search algorithm to find which commit in\n\nbase-commit: ceadf0f3cf51550166a387ec8508bb55e7883057\n-- \ngitgitgadget\n"},{"id":"483638","messageId":"CAPig+cS4J-L44a-fjQ=2bXxRj6e1qdQK8705K3NPqmTsWXBQsw@mail.gmail.com","threadId":"60413","inReplyTo":"pull.1602.git.1698004968582.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc/git-bisect: clarify `git bisect run` syntax","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2023-10-22T21:32:45Z","receivedAt":"2023-10-22T21:32:58Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, Oct 22, 2023 at 4:03 PM cousteau via GitGitGadget\n wrote:\n> The description of the `git bisect run` command syntax at the beginning\n> of the manpage is `git bisect run ...`, which isn't quite clear\n> about what `` is or what the `...` mean; one could think that it is\n> the whole (quoted) command line with all arguments in a single string,\n> or that it supports multiple commands, or that it doesn't accept\n> commands with arguments at all.\n>\n> Change to `git bisect run [...]` to clarify the syntax.\n\nOkay, makes sense.\n\n> Signed-off-by: Javier Mora \n> ---\n> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\n> @@ -26,7 +26,7 @@ on the subcommand:\n> - git bisect run ...\n> + git bisect run [...]\n\nThe output of `git bisect -h` suffers the same problem. Perhaps this\npatch can fix that, as well?\n"},{"id":"483649","messageId":"xmqqa5sap44i.fsf@gitster.g","threadId":"60413","inReplyTo":"CAPig+cS4J-L44a-fjQ=2bXxRj6e1qdQK8705K3NPqmTsWXBQsw@mail.gmail.com","subject":"Re: [PATCH] doc/git-bisect: clarify `git bisect run` syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-23T00:35:41Z","receivedAt":"2023-10-23T00:35:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> On Sun, Oct 22, 2023 at 4:03 PM cousteau via GitGitGadget\n> wrote:\n>> The description of the `git bisect run` command syntax at the beginning\n>> of the manpage is `git bisect run ...`, which isn't quite clear\n>> about what `` is or what the `...` mean; one could think that it is\n>> the whole (quoted) command line with all arguments in a single string,\n>> or that it supports multiple commands, or that it doesn't accept\n>> commands with arguments at all.\n>>\n>> Change to `git bisect run [...]` to clarify the syntax.\n>\n> Okay, makes sense.\n>\n>> Signed-off-by: Javier Mora \n>> ---\n>> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\n>> @@ -26,7 +26,7 @@ on the subcommand:\n>> - git bisect run ...\n>> + git bisect run [...]\n>\n> The output of `git bisect -h` suffers the same problem. Perhaps this\n> patch can fix that, as well?\n\nGood eyes.\n\nNot a new problem and obviously can be left outside of this simple\nupdate, but I wonder if we should eventually move these into the\nproper SYNOPSIS section. Other multi-modal commands like \"git\ncheckout\", \"git rebase\", etc. do list different forms all in the\nSYNOPSIS section.\n\nI also thought at least some commands we know the \"-h\" output and\nSYNOPSIS match, we had tests to ensure they do not drift apart. We\nwould probably want to cover more subcommands with t0450.\n\nThanks.\n"},{"id":"483651","messageId":"ZTYi55w_70ZlP8Ew@tanuki","threadId":"60413","inReplyTo":"xmqqa5sap44i.fsf@gitster.g","subject":"Re: [PATCH] doc/git-bisect: clarify `git bisect run` syntax","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2023-10-23T07:38:15Z","receivedAt":"2023-10-23T07:38:23Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sun, Oct 22, 2023 at 05:35:41PM -0700, Junio C Hamano wrote:\n> Eric Sunshine writes:\n> \n> > On Sun, Oct 22, 2023 at 4:03 PM cousteau via GitGitGadget\n> > wrote:\n> >> The description of the `git bisect run` command syntax at the beginning\n> >> of the manpage is `git bisect run ...`, which isn't quite clear\n> >> about what `` is or what the `...` mean; one could think that it is\n> >> the whole (quoted) command line with all arguments in a single string,\n> >> or that it supports multiple commands, or that it doesn't accept\n> >> commands with arguments at all.\n> >>\n> >> Change to `git bisect run [...]` to clarify the syntax.\n> >\n> > Okay, makes sense.\n> >\n> >> Signed-off-by: Javier Mora \n> >> ---\n> >> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\n> >> @@ -26,7 +26,7 @@ on the subcommand:\n> >> - git bisect run ...\n> >> + git bisect run [...]\n> >\n> > The output of `git bisect -h` suffers the same problem. Perhaps this\n> > patch can fix that, as well?\n> \n> Good eyes.\n> \n> Not a new problem and obviously can be left outside of this simple\n> update, but I wonder if we should eventually move these into the\n> proper SYNOPSIS section. Other multi-modal commands like \"git\n> checkout\", \"git rebase\", etc. do list different forms all in the\n> SYNOPSIS section.\n> \n> I also thought at least some commands we know the \"-h\" output and\n> SYNOPSIS match, we had tests to ensure they do not drift apart. We\n> would probably want to cover more subcommands with t0450.\n> \n> Thanks.\n\nIf we don't want them to drift apart I wonder whether we could instead\ngenerate the synopsis from the output of `-h`? This reduces duplication\nat the cost of a more complex build process for our manpages.\n\nNot saying that this is necessarily a good idea, just throwing it out\nthere.\n\nPatrick\n"},{"id":"483684","messageId":"CAH1-q0hrfROfQROXGoCfde4MFkEjxjSMneDcqLO1pqYpe+bN9g@mail.gmail.com","threadId":"60413","inReplyTo":"ZTYi55w_70ZlP8Ew@tanuki","subject":"Re: [PATCH] doc/git-bisect: clarify `git bisect run` syntax","fromName":"Javier Mora","fromEmail":"cousteaulecommandant@gmail.com","sentAt":"2023-10-23T16:27:17Z","receivedAt":"2023-10-23T16:27:34Z","isPatch":true,"sender":{"key":"cousteaulecommandant@gmail.com","avatar":"https://avatars.githubusercontent.com/u/6584870?v=4"},"body":"> The output of `git bisect -h` suffers the same problem. Perhaps this\n> patch can fix that, as well?\n\nCertainly possible. Probably best if I put that on a second patch\nthough (i.e. a separate commit). Or should I just squash everything\ntogether?\n\nThere are still multiple .po files containing the old string, I guess\nI don't need to touch those?\n\nSpeaking of which, looking at the .po files I've found that there's\nalso a `git bisect--helper` command; I don't know if that's relevant\nnor how to modify that.\n\n> I wonder if we should eventually move these into the\n> proper SYNOPSIS section.\n\nSeems reasonable. I was actually wondering about that.\n\nI can make an extra patch for that if you want, while I'm at it.\n\n> If we don't want them to drift apart I wonder whether we could instead\n> generate the synopsis from the output of `-h`? This reduces duplication\n\nThat's not a bad idea. Or maybe the other way around -- generate the\noutput of `-h` from the synopsis. Or generate both (manpage and help\nmessage) from a \"synopsis stub\" file; I wonder if that could be easily\ndone.\n\n\nEl lun, 23 oct 2023 a las 8:38, Patrick Steinhardt () escribió:\n>\n> On Sun, Oct 22, 2023 at 05:35:41PM -0700, Junio C Hamano wrote:\n> > Eric Sunshine writes:\n> >\n> > > On Sun, Oct 22, 2023 at 4:03 PM cousteau via GitGitGadget\n> > > wrote:\n> > >> The description of the `git bisect run` command syntax at the beginning\n> > >> of the manpage is `git bisect run ...`, which isn't quite clear\n> > >> about what `` is or what the `...` mean; one could think that it is\n> > >> the whole (quoted) command line with all arguments in a single string,\n> > >> or that it supports multiple commands, or that it doesn't accept\n> > >> commands with arguments at all.\n> > >>\n> > >> Change to `git bisect run [...]` to clarify the syntax.\n> > >\n> > > Okay, makes sense.\n> > >\n> > >> Signed-off-by: Javier Mora \n> > >> ---\n> > >> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\n> > >> @@ -26,7 +26,7 @@ on the subcommand:\n> > >> - git bisect run ...\n> > >> + git bisect run [...]\n> > >\n> > > The output of `git bisect -h` suffers the same problem. Perhaps this\n> > > patch can fix that, as well?\n> >\n> > Good eyes.\n> >\n> > Not a new problem and obviously can be left outside of this simple\n> > update, but I wonder if we should eventually move these into the\n> > proper SYNOPSIS section. Other multi-modal commands like \"git\n> > checkout\", \"git rebase\", etc. do list different forms all in the\n> > SYNOPSIS section.\n> >\n> > I also thought at least some commands we know the \"-h\" output and\n> > SYNOPSIS match, we had tests to ensure they do not drift apart. We\n> > would probably want to cover more subcommands with t0450.\n> >\n> > Thanks.\n>\n> If we don't want them to drift apart I wonder whether we could instead\n> generate the synopsis from the output of `-h`? This reduces duplication\n> at the cost of a more complex build process for our manpages.\n>\n> Not saying that this is necessarily a good idea, just throwing it out\n> there.\n>\n> Patrick\n"},{"id":"483687","messageId":"xmqqsf61ntg4.fsf@gitster.g","threadId":"60413","inReplyTo":"ZTYi55w_70ZlP8Ew@tanuki","subject":"Re: [PATCH] doc/git-bisect: clarify `git bisect run` syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-23T17:23:55Z","receivedAt":"2023-10-23T17:24:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n>> I also thought at least some commands we know the \"-h\" output and\n>> SYNOPSIS match, we had tests to ensure they do not drift apart. We\n>> would probably want to cover more subcommands with t0450.\n>> \n>> Thanks.\n>\n> If we don't want them to drift apart I wonder whether we could instead\n> generate the synopsis from the output of `-h`? This reduces duplication\n> at the cost of a more complex build process for our manpages.\n\nThere also is the cost of making it unusable to peek the source\ngit-foo.txt files as a quick way to get the usage guide, which I\nthink is a downside only felt by developers of Git (not developers\nof other projects that happen to use Git), but still a downside.\n\nBut aside from that, it is an obviously possible direction to go [*]\nand in fact I suspect we may have talked about it when Ævar made a\ngigantic effort to clean these up in Sep-Oct 2022 timeframe, which\nresulted in the series leading to a0343f30 (tests: assert consistent\nwhitespace in -h output, 2022-10-13) [*].\n\n[Footnote]\n\n * And another possibility is to go from the doc to the message\n string, which may be even more involved, but at least the code\n needs to go through the build process anyway, so the downside\n might be lessor)\n\n * https://lore.kernel.org/git/patch-v5-34.34-4de83d3d89a-20221013T153626Z-avarab@gmail.com/\n\n\n"},{"id":"483690","messageId":"xmqqjzrdnsdt.fsf@gitster.g","threadId":"60413","inReplyTo":"CAH1-q0hrfROfQROXGoCfde4MFkEjxjSMneDcqLO1pqYpe+bN9g@mail.gmail.com","subject":"Re: [PATCH] doc/git-bisect: clarify `git bisect run` syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-23T17:46:54Z","receivedAt":"2023-10-23T17:47:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Javier Mora writes:\n\n>> The output of `git bisect -h` suffers the same problem. Perhaps this\n>> patch can fix that, as well?\n>\n> Certainly possible. Probably best if I put that on a second patch\n> though (i.e. a separate commit). Or should I just squash everything\n> together?\n\nIn this case, a single patch is the way to go; otherwise we will\n(tentatively) be in an inconsistent state after applying one until\nthe other gets applied.\n\n> There are still multiple .po files containing the old string, I guess\n> I don't need to touch those?\n\nCorrect.\n\n> Speaking of which, looking at the .po files I've found that there's\n> also a `git bisect--helper` command; I don't know if that's relevant\n> nor how to modify that.\n\nbisect--helper has been retired but most of the messages used by it\nshould have been in use by bisect proper, so only the \"this message\nappears here\" comments may be wrong.\n\nIn any case, touching po/ is not in the scope of this isolated fix.\nThe i18n group has their own workflows to update the files there,\nand those touching the code and docs should not have to touch them\nin general.\n\n>> I wonder if we should eventually move these into the\n>> proper SYNOPSIS section.\n>\n> Seems reasonable. I was actually wondering about that.\n\nBut not as a part of this isolated fix.\n"},{"id":"483711","messageId":"pull.1602.v2.git.1698088990478.gitgitgadget@gmail.com","threadId":"60413","inReplyTo":"pull.1602.git.1698004968582.gitgitgadget@gmail.com","subject":"[PATCH v2] doc/git-bisect: clarify `git bisect run` syntax","fromName":"cousteau via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-10-23T19:23:10Z","receivedAt":"2023-10-23T19:25:30Z","isPatch":true,"sender":{"key":"name:cousteau","avatar":null},"body":"From: Javier Mora \n\nThe description of the `git bisect run` command syntax at the beginning\nof the manpage is `git bisect run ...`, which isn't quite clear\nabout what `` is or what the `...` mean; one could think that it is\nthe whole (quoted) command line with all arguments in a single string,\nor that it supports multiple commands, or that it doesn't accept\ncommands with arguments at all.\n\nChange to `git bisect run [...]` to clarify the syntax,\nin both the manpage and the `git bisect -h` command output.\n\nAdditionally, change `--term-{new,bad}` et al to `--term-(new|bad)`\nfor consistency with the synopsis syntax conventions.\n\nSigned-off-by: Javier Mora \n---\n doc/git-bisect: clarify git bisect run syntax\n \n I saw someone in IRC wondering about the syntax for git bisect run for a\n command with arguments, and found that its short description at the\n beginning of the manpage is not very clear (although it gets clarified\n later when it is properly described). It describes the syntax as git\n bisect run ... which is a bit confusing; it should say git bisect\n run [...], otherwise it somehow looks like you have to \"enter\n one or more commands\", and that each command is a single argument.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1602%2Fcousteaulecommandant%2Fman-git-bisect-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1602/cousteaulecommandant/man-git-bisect-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1602\n\nRange-diff vs v1:\n\n 1: ce4c60a6f4f ! 1: 8de70bb060e doc/git-bisect: clarify `git bisect run` syntax\n @@ Commit message\n or that it supports multiple commands, or that it doesn't accept\n commands with arguments at all.\n \n - Change to `git bisect run [...]` to clarify the syntax.\n + Change to `git bisect run [...]` to clarify the syntax,\n + in both the manpage and the `git bisect -h` command output.\n +\n + Additionally, change `--term-{new,bad}` et al to `--term-(new|bad)`\n + for consistency with the synopsis syntax conventions.\n \n Signed-off-by: Javier Mora \n \n ## Documentation/git-bisect.txt ##\n +@@ Documentation/git-bisect.txt: 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-(new|bad)= --term-(old|good)=]\n + \t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n + git bisect (bad|new|) []\n + git bisect (good|old|) [...]\n @@ Documentation/git-bisect.txt: on the subcommand:\n git bisect (visualize|view)\n git bisect replay \n @@ Documentation/git-bisect.txt: on the subcommand:\n git bisect help\n \n This command uses a binary search algorithm to find which commit in\n +\n + ## builtin/bisect.c ##\n +@@ builtin/bisect.c: static GIT_PATH_FUNC(git_path_bisect_first_parent, \"BISECT_FIRST_PARENT\")\n + static GIT_PATH_FUNC(git_path_bisect_run, \"BISECT_RUN\")\n + \n + #define BUILTIN_GIT_BISECT_START_USAGE \\\n +-\tN_(\"git bisect start [--term-{new,bad}= --term-{old,good}=]\" \\\n ++\tN_(\"git bisect start [--term-(new|bad)= --term-(old|good)=]\" \\\n + \t \" [--no-checkout] [--first-parent] [ [...]] [--]\" \\\n + \t \" [...]\")\n + #define BUILTIN_GIT_BISECT_STATE_USAGE \\\n +@@ builtin/bisect.c: static GIT_PATH_FUNC(git_path_bisect_run, \"BISECT_RUN\")\n + #define BUILTIN_GIT_BISECT_LOG_USAGE \\\n + \t\"git bisect log\"\n + #define BUILTIN_GIT_BISECT_RUN_USAGE \\\n +-\tN_(\"git bisect run ...\")\n ++\tN_(\"git bisect run [...]\")\n + \n + static const char * const git_bisect_usage[] = {\n + \tBUILTIN_GIT_BISECT_START_USAGE,\n\n\n Documentation/git-bisect.txt | 4 ++--\n builtin/bisect.c | 4 ++--\n 2 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\nindex 7872dba3aef..191b4a42b6d 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-(new|bad)= --term-(old|good)=]\n \t\t [--no-checkout] [--first-parent] [ [...]] [--] [...]\n git bisect (bad|new|) []\n git bisect (good|old|) [...]\n@@ -26,7 +26,7 @@ on the subcommand:\n git bisect (visualize|view)\n git bisect replay \n git bisect log\n- git bisect run ...\n+ git bisect run [...]\n git bisect help\n \n This command uses a binary search algorithm to find which commit in\ndiff --git a/builtin/bisect.c b/builtin/bisect.c\nindex 65478ef40f5..35938b05fd1 100644\n--- a/builtin/bisect.c\n+++ b/builtin/bisect.c\n@@ -26,7 +26,7 @@ static GIT_PATH_FUNC(git_path_bisect_first_parent, \"BISECT_FIRST_PARENT\")\n static GIT_PATH_FUNC(git_path_bisect_run, \"BISECT_RUN\")\n \n #define BUILTIN_GIT_BISECT_START_USAGE \\\n-\tN_(\"git bisect start [--term-{new,bad}= --term-{old,good}=]\" \\\n+\tN_(\"git bisect start [--term-(new|bad)= --term-(old|good)=]\" \\\n \t \" [--no-checkout] [--first-parent] [ [...]] [--]\" \\\n \t \" [...]\")\n #define BUILTIN_GIT_BISECT_STATE_USAGE \\\n@@ -46,7 +46,7 @@ static GIT_PATH_FUNC(git_path_bisect_run, \"BISECT_RUN\")\n #define BUILTIN_GIT_BISECT_LOG_USAGE \\\n \t\"git bisect log\"\n #define BUILTIN_GIT_BISECT_RUN_USAGE \\\n-\tN_(\"git bisect run ...\")\n+\tN_(\"git bisect run [...]\")\n \n static const char * const git_bisect_usage[] = {\n \tBUILTIN_GIT_BISECT_START_USAGE,\n\nbase-commit: ceadf0f3cf51550166a387ec8508bb55e7883057\n-- \ngitgitgadget\n"},{"id":"483715","messageId":"CAPig+cQuBwzaG7ZssGUY6k8wf8pcGZHAGLnbRy579uTPMKqwKQ@mail.gmail.com","threadId":"60413","inReplyTo":"pull.1602.v2.git.1698088990478.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc/git-bisect: clarify `git bisect run` syntax","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2023-10-23T19:36:31Z","receivedAt":"2023-10-23T19:36:45Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Oct 23, 2023 at 3:23 PM cousteau via GitGitGadget\n wrote:\n> doc/git-bisect: clarify `git bisect run` syntax\n>\n> The description of the `git bisect run` command syntax at the beginning\n> of the manpage is `git bisect run ...`, which isn't quite clear\n> about what `` is or what the `...` mean; one could think that it is\n> the whole (quoted) command line with all arguments in a single string,\n> or that it supports multiple commands, or that it doesn't accept\n> commands with arguments at all.\n>\n> Change to `git bisect run [...]` to clarify the syntax,\n> in both the manpage and the `git bisect -h` command output.\n>\n> Additionally, change `--term-{new,bad}` et al to `--term-(new|bad)`\n> for consistency with the synopsis syntax conventions.\n\nMakes sense to fix this inconsistency, as well, though the patch\nsubject becomes a bit outdated with this addition.\n\n> Signed-off-by: Javier Mora \n> ---\n> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt\n> @@ -16,7 +16,7 @@ DESCRIPTION\n> - git bisect start [--term-{new,bad}= --term-{old,good}=]\n> + git bisect start [--term-(new|bad)= --term-(old|good)=]\n> [--no-checkout] [--first-parent] [ [...]] [--] [...]\n> git bisect (bad|new|) []\n> git bisect (good|old|) [...]\n\nUpon first reading, I questioned whether changing to \nand adds value since the option names --term-new and\n--term-old already provide enough context for the reader to understand\nthe generic placeholder . However, then I noticed that the\nfollowing two lines are already referencing placeholders \nand , so perhaps this change makes sense. But...\n\n> diff --git a/builtin/bisect.c b/builtin/bisect.c\n> @@ -26,7 +26,7 @@ static GIT_PATH_FUNC(git_path_bisect_first_parent, \"BISECT_FIRST_PARENT\")\n> #define BUILTIN_GIT_BISECT_START_USAGE \\\n> - N_(\"git bisect start [--term-{new,bad}= --term-{old,good}=]\" \\\n> + N_(\"git bisect start [--term-(new|bad)= --term-(old|good)=]\" \\\n\n...now we have an inconsistency again since this text just uses the\ngeneric . However, I haven't convinced myself that we need to\ncare about this inconsistency.\n"},{"id":"483747","messageId":"CAH1-q0hNSKgr1-dtZac=z7Bx15gON0Y-1pyBM57zuXaFPaJJKQ@mail.gmail.com","threadId":"60413","inReplyTo":"CAPig+cQuBwzaG7ZssGUY6k8wf8pcGZHAGLnbRy579uTPMKqwKQ@mail.gmail.com","subject":"Re: [PATCH v2] doc/git-bisect: clarify `git bisect run` syntax","fromName":"Javier Mora","fromEmail":"cousteaulecommandant@gmail.com","sentAt":"2023-10-23T22:53:16Z","receivedAt":"2023-10-23T22:53:31Z","isPatch":true,"sender":{"key":"cousteaulecommandant@gmail.com","avatar":"https://avatars.githubusercontent.com/u/6584870?v=4"},"body":"> the patch subject becomes a bit outdated with this addition.\n\nRight; I wanted to change it to something like \"clarify `git bisect\nrun` syntax and other minor changes\" but wanted to keep the title\nconcise.\nI guess I could change it to just \"clarify `git bisect` syntax\" though\nremove the \"run\").\n\n> the following two lines are already referencing placeholders\n> and \n\nThat's why I added it; that `(bad|new|)` felt a bit awkward\nwith no previous explanation of what was.\n\n> ...now we have an inconsistency again since this text just uses the\n> generic . However, I haven't convinced myself that we need to\n> care about this inconsistency.\n\nI thought about that, but in THAT case it wasn't necessary because\n and are never used there (and I wanted to avoid\nmaking -h too long). But it's true that it feels inconsistent; I may\nadd it just for the sake of consistency.\n\nOverall, maybe I should leave that change to a separate patch, even if\nit's a minor correction. (This made more sense when I had in mind the\nplan to move everything from description to synopsis so I would need\nto touch all those lines anyway.) The changes will be compatible\nanyway (they're far away enough to not cause merge conflicts). What\ndo you think?\n"},{"id":"483749","messageId":"CAPig+cS7-YrWf=cxbq6V8FH1BdtoqAS-EKzxF-ha-A0A6_91ew@mail.gmail.com","threadId":"60413","inReplyTo":"CAH1-q0hNSKgr1-dtZac=z7Bx15gON0Y-1pyBM57zuXaFPaJJKQ@mail.gmail.com","subject":"Re: [PATCH v2] doc/git-bisect: clarify `git bisect run` syntax","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2023-10-23T23:18:18Z","receivedAt":"2023-10-23T23:18:32Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Oct 23, 2023 at 6:53 PM Javier Mora\n wrote:\n> > the patch subject becomes a bit outdated with this addition.\n>\n> Right; I wanted to change it to something like \"clarify `git bisect\n> run` syntax and other minor changes\" but wanted to keep the title\n> concise.\n> I guess I could change it to just \"clarify `git bisect` syntax\" though\n> remove the \"run\").\n\nYup.\n\n> > the following two lines are already referencing placeholders\n> > and \n>\n> That's why I added it; that `(bad|new|)` felt a bit awkward\n> with no previous explanation of what was.\n>\n> > ...now we have an inconsistency again since this text just uses the\n> > generic . However, I haven't convinced myself that we need to\n> > care about this inconsistency.\n>\n> I thought about that, but in THAT case it wasn't necessary because\n> and are never used there (and I wanted to avoid\n> making -h too long). But it's true that it feels inconsistent; I may\n> add it just for the sake of consistency.\n\nI don't feel strongly about the inconsistency at this point.\n\n> Overall, maybe I should leave that change to a separate patch, even if\n> it's a minor correction. (This made more sense when I had in mind the\n> plan to move everything from description to synopsis so I would need\n> to touch all those lines anyway.) The changes will be compatible\n> anyway (they're far away enough to not cause merge conflicts). What\n> do you think?\n\nI can certainly see the \"{new,bad}\" to \"(new|bad\") and to\n/ changes being separated out, making this a two-\nor three-patch series.\n"},{"id":"483753","messageId":"xmqqfs207uaw.fsf@gitster.g","threadId":"60413","inReplyTo":"CAH1-q0hNSKgr1-dtZac=z7Bx15gON0Y-1pyBM57zuXaFPaJJKQ@mail.gmail.com","subject":"Re: [PATCH v2] doc/git-bisect: clarify `git bisect run` syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-10-24T00:12:07Z","receivedAt":"2023-10-24T00:12:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Javier Mora writes:\n\n>> the patch subject becomes a bit outdated with this addition.\n>\n> Right; I wanted to change it to something like \"clarify `git bisect\n> run` syntax and other minor changes\" but wanted to keep the title\n> concise.\n> I guess I could change it to just \"clarify `git bisect` syntax\" though\n> remove the \"run\").\n\nQuite honestly, I think at this point we are entering into the\n\"diminishing returns\" territory. The title is still clear enough,\nand the patch is good.\n\nThanks. The patch has been merged to 'next'.\n"}]}