git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Adding Exit status documentation to all git commands starting with git status

From
NKnadim khemir <nadim@khemir.net>
Date
Dec 13, 2008, 19:36 UTC
Message-ID
<200812132036.39318.nadim@khemir.net>

I was asking on the irc channel about how to know if I need to commit. I promptely got answered but during the discussion, the few of us still awake in the middle of the night (for me at least), agreed that it would be good to have a EXIT STATUS in all the commands documentation starting with the 'status' command.

The current documentation of 'git status' does cover exit status and looks like: <original> ... shows what would be committed if the same options are given to 'git-commit'.

If there is no path that is different between the index file and the current HEAD commit (i.e., there is nothing to commit by running `git commit`), the command exits with non-zero status.

OUTPUT ------ </original>

There are different styles to add exit status, give me your input on why and why not using one or the other. I list 3 solutions and what I think about them.

<solution 1, least change, easier to recognize although all the negations and the explaination being about when the command ~fails~ makes newbies head spin for a few seconds>

... shows what would be committed if the same options are given to 'git-commit'.

EXIT STATUS ----------- The command exits with non-zero status if there is no path that is different between the index file and the current HEAD commit (i.e., there is nothing to commit by running `git commit`).

OUTPUT ------ </solution 1>

<solution 2, both zero and non zero status>

... shows what would be committed if the same options are given to 'git-commit'.

EXIT STATUS ----------- Zero status: There is a different between the index file and HEAD. Non-zero status: There is nothing to commit by running `git commit`.

OUTPUT ------ </solution 2>

<solution 3, Only zero status, non zero is easilly deducted. Clearest IMO>

... shows what would be committed if the same options are given to 'git-commit'.

EXIT STATUS ----------- Zero status: There is a different between the index and HEAD; running `git commit` would create a new commit.

OUTPUT ------ </solution 3>

A few things could be better explained:
	- The command is to be run with '-a' as option. 
	- The fact that non add'ed files are not taken into account is not
completely obvious. The first paragraph of the DESCRIPTION explains it but it  
is not the clearest explaination ever (maybe because it's not easy to explain 
and man pages are references not user manuals)
Cheers, Nadim.
Next: Junio C Hamano
Message 1 of 2 in “Adding Exit status documentation to all git commands starting with git status”
  1. nadim khemirDec 13, 2008
  2. Junio C HamanoDec 13, 2008

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.