{"thread":{"id":"2217","subject":"Convention for help in git commands?","startedAt":"2005-10-25T13:08:43Z","lastAt":"2005-10-25T22:07:08Z","messageCount":5,"participants":["Josef Weidendorfer","Junio C Hamano","Martin Langhoff"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"10577","messageId":"200510251508.43552.Josef.Weidendorfer@gmx.de","threadId":"2217","inReplyTo":null,"subject":"Convention for help in git commands?","fromName":"Josef Weidendorfer","fromEmail":"josef.weidendorfer@gmx.de","sentAt":"2005-10-25T13:08:43Z","receivedAt":"2005-10-25T13:08:43Z","isPatch":false,"sender":{"key":"josef.weidendorfer@gmx.de","avatar":null},"body":"Hi,\n\nis there a commonly accepted way how to handle help messages\nin git commands? In git-mv/git-rename, there is a full help\nmessage with description of options when \"-h\" is given.\nThis seems to be the Cogito way; git commands seem to be used\nto output an one-liner usage only, and rely on the man\npage otherwise.\n\nThis should be more consistent. Proposal:\n* All git commands should react on command line option \"-h\"\nfor help, dumping a few lines to stderr, prefixed by \"usage:\", giving\nthe command usage without further descriptions. For the usage\noutput, use the base name of the command, and not the absolute\npath to the binary.\n* For commands which need at least one argument, the usage\nis also printed, if the command is run without argument\n* On a error condition, prefix the message with \"error:\", and\ndo not print out anything else (like the usage line, or things\nproduced by the PERL \"die\", which appends \"at scriptname line nn\").\n\nPerhaps these things should be done only for commands of the\ngit lightwight porcelain?\n\nJosef\n"},{"id":"10602","messageId":"7vfyqpe87x.fsf@assigned-by-dhcp.cox.net","threadId":"2217","inReplyTo":"200510251508.43552.Josef.Weidendorfer@gmx.de","subject":"Re: Convention for help in git commands?","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-10-25T18:56:34Z","receivedAt":"2005-10-25T18:56:34Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josef Weidendorfer writes:\n\n> * All git commands should react on command line option \"-h\"\n> for help, dumping a few lines to stderr, prefixed by \"usage:\", giving\n> the command usage without further descriptions. For the usage\n> output, use the base name of the command, and not the absolute\n> path to the binary.\n\nIt drives me nuts when an error message shows only basename not\nfull path and I find out that I was running a wrong executable\nmuch later after wasting a lot of time trying to debug it. But\nI think \"usage: \" saying the basename only is user friendly and\na good convention.\n\n> * For commands which need at least one argument, the usage\n> is also printed, if the command is run without argument\n\nThis is slightly debatable. I'd rather see it error out for one\nthing, and we might want to do a sane default given no arguments\nlater.\n\n> Perhaps these things should be done only for commands of the\n> git lightwight porcelain?\n\nProbably.\n"},{"id":"10605","messageId":"46a038f90510251324s50911b88pb5eabb304644bcad@mail.gmail.com","threadId":"2217","inReplyTo":"7vfyqpe87x.fsf@assigned-by-dhcp.cox.net","subject":"Re: Convention for help in git commands?","fromName":"Martin Langhoff","fromEmail":"martin.langhoff@gmail.com","sentAt":"2005-10-25T20:24:48Z","receivedAt":"2005-10-25T20:24:48Z","isPatch":false,"sender":{"key":"martin.langhoff@gmail.com","avatar":"https://gravatar.com/avatar/1e3f311b6c4c15836501901ca58f8c0b0667246488084ba524d8bc9867e22fd9?d=mp&s=160"},"body":"On 10/26/05, Junio C Hamano wrote:\n> > * For commands which need at least one argument, the usage\n> > is also printed, if the command is run without argument\n>\n> This is slightly debatable. I'd rather see it error out for one\n> thing, and we might want to do a sane default given no arguments\n> later.\n\nThis could lead to subtle bugs when git is used by porcelains. If\nthere are going to be changes in default behaviours, let's have them\nsoon-ish ;-)\n\ncheers,\n\n\nmartin\n"},{"id":"10613","messageId":"200510252335.47917.Josef.Weidendorfer@gmx.de","threadId":"2217","inReplyTo":"46a038f90510251324s50911b88pb5eabb304644bcad@mail.gmail.com","subject":"Re: Convention for help in git commands?","fromName":"Josef Weidendorfer","fromEmail":"josef.weidendorfer@gmx.de","sentAt":"2005-10-25T21:35:47Z","receivedAt":"2005-10-25T21:35:47Z","isPatch":false,"sender":{"key":"josef.weidendorfer@gmx.de","avatar":null},"body":"On Tuesday 25 October 2005 22:24, you wrote:\n> On 10/26/05, Junio C Hamano wrote:\n> > > * For commands which need at least one argument, the usage\n> > > is also printed, if the command is run without argument\n> >\n> > This is slightly debatable. I'd rather see it error out for one\n> > thing, and we might want to do a sane default given no arguments\n> > later.\n> \n> This could lead to subtle bugs when git is used by porcelains. If\n> there are going to be changes in default behaviours, let's have them\n> soon-ish ;-)\n\nWhat is the difference for a porcelain between error out,\npresumable with an error message, and printing the usage alone?\n\nIs there any dependency of porcelains to the fact the e.g.\n\"git-rev-list\" currently does nothing if not called with a\ncommit-id? Somehow I think \"git-rev-list\" should give an error,\nas the usage string (with lots of options on a line of its own ?!)\nrequires a commit-id as argument.\n\nBTW, the error message of \"mv\" is:\n===\nmv: missing file operand\nTry `mv --help' for more information.\n===\nWhat about something similar to this? Mentioning the command\nwhich triggered the error is probably a good idea.\n\nAnd I would add as another convention:\n* \"git-cmd -h\" always should give the usage, and not error out\nwith \"fatal: Not a git repository\" before.\n\nJosef\n"},{"id":"10617","messageId":"46a038f90510251507oe62ce42i86e6d4cf8200f20@mail.gmail.com","threadId":"2217","inReplyTo":"200510252335.47917.Josef.Weidendorfer@gmx.de","subject":"Re: Convention for help in git commands?","fromName":"Martin Langhoff","fromEmail":"martin.langhoff@gmail.com","sentAt":"2005-10-25T22:07:08Z","receivedAt":"2005-10-25T22:07:08Z","isPatch":false,"sender":{"key":"martin.langhoff@gmail.com","avatar":"https://gravatar.com/avatar/1e3f311b6c4c15836501901ca58f8c0b0667246488084ba524d8bc9867e22fd9?d=mp&s=160"},"body":"On 10/26/05, Josef Weidendorfer wrote:\n> On Tuesday 25 October 2005 22:24, you wrote:\n> > On 10/26/05, Junio C Hamano wrote:\n> > > > * For commands which need at least one argument, the usage\n> > > > is also printed, if the command is run without argument\n> > >\n> > > This is slightly debatable. I'd rather see it error out for one\n> > > thing, and we might want to do a sane default given no arguments\n> > > later.\n> >\n> > This could lead to subtle bugs when git is used by porcelains. If\n> > there are going to be changes in default behaviours, let's have them\n> > soon-ish ;-)\n>\n> What is the difference for a porcelain between error out,\n> presumable with an error message, and printing the usage alone?\n\nSorry! My comment was aimed at the \"do a sane default given no\narguments later\" part of Junio's post. Error vs help messages don't\naffect porcelains if you check your tty and avoid spitting out a help\nmessage when invoked from a script ;-)\n\ncheers,\n\n\nmartin\n"}]}