{"thread":{"id":"50886","subject":"git glossary --help ?","startedAt":"2019-04-06T17:32:01Z","lastAt":"2019-04-08T01:08:54Z","messageCount":8,"participants":["Philip Oakley","Andreas Schwab","Duy Nguyen","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"373330","messageId":"05e6a0ad-36ea-e594-f253-ded3e5392375@iee.org","threadId":"50886","inReplyTo":null,"subject":"git glossary --help ?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-04-06T17:31:59Z","receivedAt":"2019-04-06T17:32:01Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Following the discussions about the tag peeling issue, I thought to have \na look at what the git glossary says.\n\nI had it in my head that when the git guides were linked to the help \nsystem, that the --help option provided a short circuit direct to help \nitem. However this did not happen.\n\nI found that the capability had been lost, which given that a lot of the \nunderpinning knowledge is in the guides this would appear to be a loss.\n\nI don't have an older version to test, but I thought I remember the \ncapability from about the time of my 65f98358c0 (\"builtin/help.c: add \n--guide option\", 2013-04-02).\n\nHave I misremembered the --help capability?\n\ncc'ing Duy in case he remembers something from the recent update\n\nAs a side note, the glossary does mention a few times the tag of tag \ncapability but doesn't mention the peel/no-peel distinctions.\n-- \nPhilip\n"},{"id":"373332","messageId":"87v9zr57kl.fsf@igel.home","threadId":"50886","inReplyTo":"05e6a0ad-36ea-e594-f253-ded3e5392375@iee.org","subject":"Re: git glossary --help ?","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2019-04-06T18:09:46Z","receivedAt":"2019-04-06T18:09:51Z","isPatch":false,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"On Apr 06 2019, Philip Oakley wrote:\n\n> Following the discussions about the tag peeling issue, I thought to have a\n> look at what the git glossary says.\n>\n> I had it in my head that when the git guides were linked to the help\n> system, that the --help option provided a short circuit direct to help\n> item. However this did not happen.\n\n$ git help glossary\n\nAndreas.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 7578 EB47 D4E5 4D69 2510 2552 DF73 E780 A9DA AEC1\n\"And now for something completely different.\"\n"},{"id":"373337","messageId":"0bbe60e7-15ce-775c-bfcb-d2c660361e80@iee.org","threadId":"50886","inReplyTo":"87v9zr57kl.fsf@igel.home","subject":"Re: git glossary --help ?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-04-06T20:27:42Z","receivedAt":"2019-04-06T20:27:46Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Andreas,\n\nOn 06/04/2019 19:09, Andreas Schwab wrote:\n> On Apr 06 2019, Philip Oakley wrote:\n>\n>> Following the discussions about the tag peeling issue, I thought to have a\n>> look at what the git glossary says.\n>>\n>> I had it in my head that when the git guides were linked to the help\n>> system, that the --help option provided a short circuit direct to help\n>> item. However this did not happen.\n> $ git help glossary\n>\n> Andreas.\n>\nThanks. I was aware of that form, but as I remember it, as part of the \n'git' command processing, there was an immediate shortcut if --help was \nan option, that would essentially re-write the cli as 'git help \ncommand', such that 'git foo --help' would become 'git help foo' and the \nhelp system would then provide the right long form help, including the \nguides and docs (excepting the user-manual, which is \nunfortunate, but ..)\n\nMy question was whether the older systems did that re-write as \ndescribed, should someone have one immediately to hand.\nPhilip\n"},{"id":"373342","messageId":"CACsJy8DE4WfbU2y8+__4qD7V5FLodKjxX-bu+seE8mh65q8FYQ@mail.gmail.com","threadId":"50886","inReplyTo":"05e6a0ad-36ea-e594-f253-ded3e5392375@iee.org","subject":"Re: git glossary --help ?","fromName":"Duy Nguyen","fromEmail":"pclouds@gmail.com","sentAt":"2019-04-07T03:20:28Z","receivedAt":"2019-04-07T03:20:56Z","isPatch":false,"sender":{"key":"pclouds@gmail.com","avatar":"https://avatars.githubusercontent.com/u/720?v=4"},"body":"On Sun, Apr 7, 2019 at 12:31 AM Philip Oakley wrote:\n>\n> Following the discussions about the tag peeling issue, I thought to have\n> a look at what the git glossary says.\n>\n> I had it in my head that when the git guides were linked to the help\n> system, that the --help option provided a short circuit direct to help\n> item. However this did not happen.\n>\n> I found that the capability had been lost, which given that a lot of the\n> underpinning knowledge is in the guides this would appear to be a loss.\n>\n> I don't have an older version to test, but I thought I remember the\n> capability from about the time of my 65f98358c0 (\"builtin/help.c: add\n> --guide option\", 2013-04-02).\n>\n> Have I misremembered the --help capability?\n>\n> cc'ing Duy in case he remembers something from the recent update\n\nPhew... I didn't break anything!\n\nThat behavior has been gone since 2c6b6d9f7d (help: make option --help\nopen man pages only for Git commands, 2016-08-26). Ralf did not\nmention why he thought \"git --help\" was a bad idea. But it\nwas considered a bug by Junio [1]\n\n[1] https://public-inbox.org/git/CAPc5daXicjUDi6B-MA8Sn=_UZ_jHvc8SE4ZXt2dHbbDQkD7=WA@mail.gmail.com/\n-- \nDuy\n"},{"id":"373348","messageId":"8e40eb85-0368-d12f-f238-acababdcd858@talktalk.net","threadId":"50886","inReplyTo":"CACsJy8DE4WfbU2y8+__4qD7V5FLodKjxX-bu+seE8mh65q8FYQ@mail.gmail.com","subject":"Re: git glossary --help ?","fromName":"Philip Oakley","fromEmail":"philipoakley@talktalk.net","sentAt":"2019-04-07T11:52:09Z","receivedAt":"2019-04-07T11:52:14Z","isPatch":false,"sender":{"key":"philipoakley@talktalk.net","avatar":null},"body":"Hi Duy,\n\nOn 07/04/2019 04:20, Duy Nguyen wrote:\n> On Sun, Apr 7, 2019 at 12:31 AM Philip Oakley wrote:\n>> Following the discussions about the tag peeling issue, I thought to have\n>> a look at what the git glossary says.\n>>\n>> I had it in my head that when the git guides were linked to the help\n>> system, that the --help option provided a short circuit direct to help\n>> item. However this did not happen.\n>>\n>> I found that the capability had been lost, which given that a lot of the\n>> underpinning knowledge is in the guides this would appear to be a loss.\n>>\n>> I don't have an older version to test, but I thought I remember the\n>> capability from about the time of my 65f98358c0 (\"builtin/help.c: add\n>> --guide option\", 2013-04-02).\n>>\n>> Have I misremembered the --help capability?\n>>\n>> cc'ing Duy in case he remembers something from the recent update\n> Phew... I didn't break anything!\n>\n> That behavior has been gone since 2c6b6d9f7d (help: make option --help\n> open man pages only for Git commands, 2016-08-26). Ralf did not\n> mention why he thought \"git --help\" was a bad idea. But it\n> was considered a bug by Junio [1]\n>\n> [1] https://public-inbox.org/git/CAPc5daXicjUDi6B-MA8Sn=_UZ_jHvc8SE4ZXt2dHbbDQkD7=WA@mail.gmail.com/\nThanks for the link. I see I responded later in the thread but didn't \nfollow it up sufficiently (not sure what I was doing back then.. summer \nbreak maybe).\n\nI do think we are sometimes a bit dismissive of features (accidental \nbias) that help the general user in getting help. If we think that 'git \nhelp' is the (one) right way of providing access to manuals (such as the \nconcept guides) then maybe we shouldn't have the ubiquitous --help \noption for all the commands. Or,\n\nOr, we should be liberal in what we accept from others (Postel's Law). \nIt is normal to type 'git foo --help'. So maybe allow these multiple \nways of accessing the documentation. Given the update to the command \nlist capability, I'll add it to my todo list to see if we can accept \nguide names with --help and, one way or another, get folk to the right \nplace (the guide or command they should have used/requested).\n-- \nPhilip\n"},{"id":"373352","messageId":"xmqqlg0mc4mk.fsf@gitster-ct.c.googlers.com","threadId":"50886","inReplyTo":"CACsJy8DE4WfbU2y8+__4qD7V5FLodKjxX-bu+seE8mh65q8FYQ@mail.gmail.com","subject":"Re: git glossary --help ?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-04-07T13:43:47Z","receivedAt":"2019-04-07T13:43:52Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Duy Nguyen writes:\n\n> Phew... I didn't break anything!\n>\n> That behavior has been gone since 2c6b6d9f7d (help: make option --help\n> open man pages only for Git commands, 2016-08-26). Ralf did not\n> mention why he thought \"git --help\" was a bad idea. But it\n> was considered a bug by Junio [1]\n>\n> [1] https://public-inbox.org/git/CAPc5daXicjUDi6B-MA8Sn=_UZ_jHvc8SE4ZXt2dHbbDQkD7=WA@mail.gmail.com/\n\nI do not think you are reading me correctly.\n\nYes, I do consider that \"git foo --help\" that does not say \"there is\nno subcomand 'foo' in Git suite\" is a bug. But that is only for\n'foo' that is clearly meant as a command.\n\nI do not imagine anybody labelling \"git help glossary\" as a bug.\n\nI am fairly neutral about \"git glossary --help\". I personally would\nnot ask git like so, as \"glossary\" is clearly not a command name,\nand the \"--help\" option is clearly meant as an option to the\nsubcommand, which means that the request logically does not make\nmuch sense.\n\nBut unlike \"git foo --help\", if the word that ought to name a\nsubcommand instead names a known concept, e.g. \"glossary\", I do not\nthink it is too bad if we DWIMmed what the user meant to say,\ni.e. turning \"git glossary --help\" into \"git help glossary\".\n\n\n"},{"id":"373374","messageId":"3de9d8bc-f9d1-bf09-def6-71e5ed418225@iee.org","threadId":"50886","inReplyTo":"xmqqlg0mc4mk.fsf@gitster-ct.c.googlers.com","subject":"Re: git glossary --help ?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2019-04-07T22:42:39Z","receivedAt":"2019-04-07T22:42:43Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Junio,\n\nOn 07/04/2019 14:43, Junio C Hamano wrote:\n> Duy Nguyen writes:\n>\n>> Phew... I didn't break anything!\n>>\n>> That behavior has been gone since 2c6b6d9f7d (help: make option --help\n>> open man pages only for Git commands, 2016-08-26). Ralf did not\n>> mention why he thought \"git --help\" was a bad idea. But it\n>> was considered a bug by Junio [1]\n>>\n>> [1] https://public-inbox.org/git/CAPc5daXicjUDi6B-MA8Sn=_UZ_jHvc8SE4ZXt2dHbbDQkD7=WA@mail.gmail.com/\n> I do not think you are reading me correctly.\n>\n> Yes, I do consider that \"git foo --help\" that does not say \"there is\n> no subcomand 'foo' in Git suite\" is a bug. But that is only for\n> 'foo' that is clearly meant as a command.\n>\n> I do not imagine anybody labelling \"git help glossary\" as a bug.\n>\n> I am fairly neutral about \"git glossary --help\". I personally would\n> not ask git like so, as \"glossary\" is clearly not a command name,\n> and the \"--help\" option is clearly meant as an option to the\n> subcommand, which means that the request logically does not make\n> much sense.\n>\n> But unlike \"git foo --help\", if the word that ought to name a\n> subcommand instead names a known concept, e.g. \"glossary\", I do not\n> think it is too bad if we DWIMmed what the user meant to say,\n> i.e. turning \"git glossary --help\" into \"git help glossary\".\n>\nGiven the earlier report that started the thread Duy linked, I guess \nthere will need to be a balance between the two expectations.\n\nThe DWIMming  may need to both report that it's not a command, but then \noffer the concept guide as the primary target if correct, or perhaps as \none of the alternate \"commands\" if closely named to a guide (e.g. \nrevisions vs revision).\n\nOne of the issues back then was the lack of a complete list of 'guides' \nto check against, so the badly spelt command logic wasn't brought into play.\n--\nPhilip\n"},{"id":"373380","messageId":"xmqqd0lxcnle.fsf@gitster-ct.c.googlers.com","threadId":"50886","inReplyTo":"3de9d8bc-f9d1-bf09-def6-71e5ed418225@iee.org","subject":"Re: git glossary --help ?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-04-08T01:06:21Z","receivedAt":"2019-04-08T01:08:54Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n>> But unlike \"git foo --help\", if the word that ought to name a\n>> subcommand instead names a known concept, e.g. \"glossary\", I do not\n>> think it is too bad if we DWIMmed what the user meant to say,\n>> i.e. turning \"git glossary --help\" into \"git help glossary\".\n>>\n> Given the earlier report that started the thread Duy linked, I guess\n> there will need to be a balance between the two expectations.\n>\n> The DWIMming may need to both report that it's not a command, but\n> then offer the concept guide as the primary target if correct, or\n> perhaps as one of the alternate \"commands\" if closely named to a guide\n> (e.g. revisions vs revision).\n\nThe \"or perhaps\" part feels a bit overkill, but I do not mind seeing\nit if somebody does it cleanly and correctly ;-)\n\n> One of the issues back then was the lack of a complete list of\n> 'guides' to check against, so the badly spelt command logic wasn't\n> brought into play.\n\nYeah, thanks for spelling it out; I think we are on the same page,\nhaving followed the same discussion in the archive, where we knew\nthat a list of 'concepts-not-commands' would help the error message\nsituation.\n\n"}]}