{"thread":{"id":"44105","subject":"Why are there multiple ways to get the manual in Git?","startedAt":"2016-09-17T17:47:59Z","lastAt":"2016-09-19T16:22:14Z","messageCount":8,"participants":["Andrew Johnson","Fredrik Gustafsson","Philip Oakley","Christian Couder","Jakub Narębski","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"302103","messageId":"CAM_5GX48gDAZSvAWnxO5n8uhYf8vmfAJ88_31_ewsQxyPfF7iA@mail.gmail.com","threadId":"44105","inReplyTo":null,"subject":"Why are there multiple ways to get the manual in Git?","fromName":"Andrew Johnson","fromEmail":"ajohnson388@gmail.com","sentAt":"2016-09-17T17:47:52Z","receivedAt":"2016-09-17T17:47:59Z","isPatch":false,"sender":{"key":"ajohnson388@gmail.com","avatar":null},"body":"Hi,\n\nI was curious as to why the developers of Git decided to have three\nmethods to get the manual for a verb. I am a developer who strives to\nunderstand Git to its fullest extent, and will share any information\ngiven on this question.\n\nWhile reading Pro Git 2nd Ed. I came across these three methods:\n\n$ git help \n$ git --help\n$ man git-\n\nI tested all three to confirm they were equivalent.\n\nWhat was the motivation behind the complication, if any? I presume\nmost developers would not provide multiple commands that do the same\nthing for absolutely no reason, so I led myself to ask this question.\n\nRespectfully,\nAndrew Johnson\n"},{"id":"302105","messageId":"20160917183919.GJ20666@paksenarrion.iveqy.com","threadId":"44105","inReplyTo":"CAM_5GX48gDAZSvAWnxO5n8uhYf8vmfAJ88_31_ewsQxyPfF7iA@mail.gmail.com","subject":"Re: Why are there multiple ways to get the manual in Git?","fromName":"Fredrik Gustafsson","fromEmail":"iveqy@iveqy.com","sentAt":"2016-09-17T18:39:19Z","receivedAt":"2016-09-17T18:32:38Z","isPatch":false,"sender":{"key":"iveqy@iveqy.com","avatar":"https://avatars.githubusercontent.com/u/761743?v=4"},"body":"On Sat, Sep 17, 2016 at 01:47:52PM -0400, Andrew Johnson wrote:\n> $ git help \n> $ git --help\n> $ man git-\n> \n> I tested all three to confirm they were equivalent.\n\nWhile I'm not able to answer your question, I can shred a little light\nabout them not being equal. For example using a windows machine\n\n$ man git \n\ndoes not work and\n\n$ git help \n\nopens a webbrowser instead of a man page. Using a unix system I would\nhowever assume that\n\n$ man git \n\nwould work since it's the standard way of getting help on those systems.\n\n-- \nFredrik Gustafsson\n\nphone: +46 733-608274\ne-mail: iveqy@iveqy.com\nwebsite: http://www.iveqy.com\n"},{"id":"302107","messageId":"0B172DDC12B24525AF5FCEC4216B69E3@PhilipOakley","threadId":"44105","inReplyTo":"20160917183919.GJ20666@paksenarrion.iveqy.com","subject":"Re: Why are there multiple ways to get the manual in Git?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-09-17T19:12:01Z","receivedAt":"2016-09-17T19:12:07Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Fredrik Gustafsson\" \n> On Sat, Sep 17, 2016 at 01:47:52PM -0400, Andrew Johnson wrote:\n>> $ git help \n>> $ git --help\n>> $ man git-\n>>\n>> I tested all three to confirm they were equivalent.\n\nIt is (IIUC) in a general sort of way \"by design\", and a little bit of \naccident.\n\n>\n> While I'm not able to answer your question, I can shred a little light\n> about them not being equal. For example using a windows machine\n>\n> $ man git \n>\n> does not work and\n>\n> $ git help \n>\n> opens a webbrowser instead of a man page. Using a unix system I would\n> however assume that\n>\n> $ man git \n>\n> would work since it's the standard way of getting help on those systems.\n>\n> -- \n\nHistorically git was a set of shell scripts named git-*, so each stood \nalone.\n\nThen there was the great consolidation (around V1.6?) which created the \nmodern `git ' approach, with every command normally having -h \nand --help options for short form usage and long form man pages.\n\nThe option capability became standardised. Also a `git help ` command \nwas created. Underneath there are still the (backward compatible) git-* \nforms. The help command allowed selection of display type, so that on \nUnix/Linux man was the norm, while an --html (or --web) option is available \nfor those who like the pretty browser view\n\nThe help commnad just converts the parameters to achieve the expected \ndisplay (with various fallbacks if the command or guide is missing, etc)\n\nMeanwhile on Windows, the man facility was not ported as part of git, so it \ndefaults to the --web version. If you are on Windows, and download the SDK \nas well you can install the man viewer and other goodies\n\n--\nPhilip\n\n"},{"id":"302108","messageId":"CAP8UFD3TPeqY_O-Rc0rvLMO=XVxRMTMwq3gftpnx5LJh6WOZ1A@mail.gmail.com","threadId":"44105","inReplyTo":"20160917183919.GJ20666@paksenarrion.iveqy.com","subject":"Re: Why are there multiple ways to get the manual in Git?","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2016-09-17T19:21:48Z","receivedAt":"2016-09-17T19:21:55Z","isPatch":false,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Sat, Sep 17, 2016 at 8:39 PM, Fredrik Gustafsson wrote:\n> On Sat, Sep 17, 2016 at 01:47:52PM -0400, Andrew Johnson wrote:\n>> $ git help \n>> $ git --help\n>> $ man git-\n>>\n>> I tested all three to confirm they were equivalent.\n\nMaybe it will be easier to understand if you try:\n\n$ git help help\n\nor\n\n$ git help --help\n\nor\n\n$ man git-help\n\n:-)\n\n> While I'm not able to answer your question, I can shred a little light\n> about them not being equal. For example using a windows machine\n>\n> $ man git \n\n(It should be \"git-\" above.)\n\n> does not work and\n>\n> $ git help \n>\n> opens a webbrowser instead of a man page.\n\nYeah, it is one of the reasons.\nThere are systems where \"man\" is not the standard ways to get help,\nand text on the command line is not the prefered format for help\ncontent.\nSo the \"git help\" command has different default depending on the OS to\nbetter suit user expectations on each OS.\nThis way people can just be teached to use \"git help\" and that will do\nsomething sensible everywhere.\n\n> Using a unix system I would\n> however assume that\n>\n> $ man git \n\n(Again it should be \"git-\" above.)\n\n> would work since it's the standard way of getting help on those systems.\n\nYeah, so we need that to work to make people happy on unix systems.\n\nAnother reason is that \"git help\" provides more configurability and\nmore features like its -a and -g options.\nIt could provide even more in the future, like options to search in\nthe documentation.\n"},{"id":"302110","messageId":"223e818d-6d10-2679-c2d0-150011e74a59@gmail.com","threadId":"44105","inReplyTo":"20160917183919.GJ20666@paksenarrion.iveqy.com","subject":"Re: Why are there multiple ways to get the manual in Git?","fromName":"Jakub Narębski","fromEmail":"jnareb@gmail.com","sentAt":"2016-09-18T10:21:20Z","receivedAt":"2016-09-18T10:21:40Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"W dniu 17.09.2016 o 20:39, Fredrik Gustafsson pisze:\n> On Sat, Sep 17, 2016 at 01:47:52PM -0400, Andrew Johnson wrote:\n\n>> $ git help \n>> $ git --help\n>> $ man git-\n>>\n>> I tested all three to confirm they were equivalent.\n> \n> While I'm not able to answer your question, I can shred a little light\n> about them not being equal. For example using a windows machine\n> \n> $ man git-\n> \n> does not work and\n> \n> $ git help \n> \n> opens a webbrowser instead of a man page. Using a unix system I would\n> however assume that\n> \n> $ man git-\n> \n> would work since it's the standard way of getting help on those systems.\n\nThere is also additional difference. There are help pages which are\nnot about specific Git command, but about concepts (gitcli, gitrevisions,\ngithooks, gitrepository-layout, gitglossary), or about files (gitignore,\ngitattributes, to some extent githooks).\n\nThose are only accessible with `git help ` or, on OS with\ninstalled 'man', also `man `.\n\nJust FYI\n-- \nJakub Narębski\n"},{"id":"302111","messageId":"630656BFF8F84E43A2E4C67138A9A675@PhilipOakley","threadId":"44105","inReplyTo":"223e818d-6d10-2679-c2d0-150011e74a59@gmail.com","subject":"Re: Why are there multiple ways to get the manual in Git?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-09-18T10:51:41Z","receivedAt":"2016-09-18T10:51:50Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Jakub Narębski\" \n>W dniu 17.09.2016 o 20:39, Fredrik Gustafsson pisze:\n>> On Sat, Sep 17, 2016 at 01:47:52PM -0400, Andrew Johnson wrote:\n>\n>>> $ git help \n>>> $ git --help\n>>> $ man git-\n>>>\n>>> I tested all three to confirm they were equivalent.\n>>\n>> While I'm not able to answer your question, I can shred a little light\n>> about them not being equal. For example using a windows machine\n>>\n>> $ man git-\n>>\n>> does not work and\n>>\n>> $ git help \n>>\n>> opens a webbrowser instead of a man page. Using a unix system I would\n>> however assume that\n>>\n>> $ man git-\n>>\n>> would work since it's the standard way of getting help on those systems.\n>\n> There is also additional difference. There are help pages which are\n> not about specific Git command, but about concepts (gitcli, gitrevisions,\n> githooks, gitrepository-layout, gitglossary), or about files (gitignore,\n> gitattributes, to some extent githooks).\n>\n> Those are only accessible with `git help ` or, on OS with\n> installed 'man', also `man `.\n\nThe `git revisions --help` does work ;-) But like you say, its apparent \n\"command\" name is 'gitrevisions'.\n\nThus real commands gave a git-command name, while concepts have a gitconcept \nname which can then be found via the man command.\n\n--\nPhilip \n\n"},{"id":"302143","messageId":"xmqqlgynhocy.fsf@gitster.mtv.corp.google.com","threadId":"44105","inReplyTo":"630656BFF8F84E43A2E4C67138A9A675@PhilipOakley","subject":"Re: Why are there multiple ways to get the manual in Git?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-09-19T15:59:41Z","receivedAt":"2016-09-19T15:59:49Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> The `git revisions --help` does work ;-)\n\nNot anymore ;-)\n\nI think Ralf Thielow fixed it recently.\n\n"},{"id":"302149","messageId":"15B3BA8028D444A0B458BEDF18929D4C@PhilipOakley","threadId":"44105","inReplyTo":"xmqqlgynhocy.fsf@gitster.mtv.corp.google.com","subject":"Re: Why are there multiple ways to get the manual in Git?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2016-09-19T16:22:10Z","receivedAt":"2016-09-19T16:22:14Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> \"Philip Oakley\" writes:\n> \n>> The `git revisions --help` does work ;-)\n> \n> Not anymore ;-)\n> \n> I think Ralf Thielow fixed it recently.\n\nhmm, I sort of though it would still work with a valid guide.\n\nI'd only checked with my last GfW version.\n--\nhey ho\nPhilip\n"}]}