{"thread":{"id":"16717","subject":"Adding Exit status documentation to all git commands starting with git status","startedAt":"2008-12-13T19:36:39Z","lastAt":"2008-12-13T20:04:52Z","messageCount":2,"participants":["nadim khemir","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"97809","messageId":"200812132036.39318.nadim@khemir.net","threadId":"16717","inReplyTo":null,"subject":"Adding Exit status documentation to all git commands starting with git status","fromName":"nadim khemir","fromEmail":"nadim@khemir.net","sentAt":"2008-12-13T19:36:39Z","receivedAt":"2008-12-13T19:36:39Z","isPatch":false,"sender":{"key":"nadim@khemir.net","avatar":null},"body":"I was asking on the irc channel about how to know if I need to commit. I \npromptely got answered but during the discussion, the few of us still awake \nin the middle of the night (for me at least), agreed that it would be good to \nhave a EXIT STATUS in all the commands documentation starting with \nthe 'status' command.\n\nThe current documentation of 'git status' does cover exit status and looks \nlike:\n<original>\n...\nshows what would be committed if the same options are given to\n'git-commit'.\n\nIf there is no path that is different between the index file and\nthe current HEAD commit (i.e., there is nothing to commit by running\n`git commit`), the command exits with non-zero status.\n\n\nOUTPUT\n------\n</original>\n\nThere are different styles to add exit status, give me your input on why and \nwhy not using one or the other. I list 3 solutions and what I think about \nthem.\n\n<solution 1, least change, easier to recognize although all the negations and \nthe explaination being about when the command ~fails~ makes newbies head spin \nfor a few seconds>\n\n...\nshows what would be committed if the same options are given to\n'git-commit'.\n\nEXIT STATUS\n-----------\nThe command exits with non-zero status if there is no path that is \ndifferent between the index file and the current HEAD commit (i.e.,\nthere is nothing to commit by running `git commit`).\n\n\nOUTPUT\n------\n</solution 1>\n\n\n\n<solution 2, both zero and non zero status>\n\n...\nshows what would be committed if the same options are given to\n'git-commit'.\n\nEXIT STATUS\n-----------\nZero status:      There is a different between the index file and HEAD.\nNon-zero status:  There is nothing to commit by running `git commit`. \n\n\nOUTPUT\n------\n</solution 2>\n\n\n\n<solution 3, Only zero status, non zero is easilly deducted. Clearest IMO>\n\n...\nshows what would be committed if the same options are given to\n'git-commit'.\n\nEXIT STATUS\n-----------\nZero status: There is a different between the index and HEAD; running \n`git commit` would create a new commit. \n\n\nOUTPUT\n------\n</solution 3>\n\n\n\nA few things could be better explained:\n\t- The command is to be run with '-a' as option. \n\t- The fact that non add'ed files are not taken into account is not\ncompletely obvious. The first paragraph of the DESCRIPTION explains it but it  \nis not the clearest explaination ever (maybe because it's not easy to explain \nand man pages are references not user manuals)\n\nCheers, Nadim.\n"},{"id":"97810","messageId":"7v4p176duj.fsf@gitster.siamese.dyndns.org","threadId":"16717","inReplyTo":"200812132036.39318.nadim@khemir.net","subject":"Re: Adding Exit status documentation to all git commands starting with git status","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-12-13T20:04:52Z","receivedAt":"2008-12-13T20:04:52Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"nadim khemir <nadim@khemir.net> writes:\n\n> There are different styles to add exit status, give me your input on why and \n> why not using one or the other. I list 3 solutions and what I think about \n> them.\n\nNo matter what you do, I think EXIT STATUS section should consistently\ncome near the end of the document, immediately before SEE ALSO, which is\nwhere people who know how manual pages are written expect to find it.\n\n> EXIT STATUS\n> -----------\n> The command exits with non-zero status if there is no path that is \n> different between the index file and the current HEAD commit (i.e.,\n> there is nothing to commit by running `git commit`).\n\nProse is much easier to read as long as it is brief enough, than two-item\nenumeration:\n\n> EXIT STATUS\n> -----------\n> Zero status:      There is a different between the index file and HEAD.\n> Non-zero status:  There is nothing to commit by running `git commit`. \n\nwhose use of \"Zero status\" makes it look doubly funny (traditionally\nmanual pages do not seem to spell out exit status 0 as \"zero\", but\n\"non-zero\" is Ok).\n\nAvoid talking about only one side of the condition if you can without\nbeing too verbose.\n\n        The command exits with status 0 if there is something to commit by\n        running `git commit` with corresponding arguments, and non-zero\n        otherwise.\n"}]}