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

[Leftoverbits] exit code clean-up?

From
Junio C Hamano <gitster@pobox.com>
Date
Aug 16, 2023, 17:04 UTC
Message-ID
<xmqqsf8iex5v.fsf_-_@gitster.g>
In-Reply-To
<xmqqjztvezen.fsf@gitster.g>

Patrick earlier found that Gitaly's CI pipeline was being overly picky and complained about the unintended change of the exit code of "git fetch" in the affected codepath from 128 to 1 in a recent change that went to 'next', made by 7ba7c52d (upload-pack: fix race condition in error messages, 2023-08-10).

The thing is, we follow that exiting with 0 is success, and exiting with non-zero means failure, and we generally do not specify which non-zero value is used for the latter in our documentation. This particular case (i.e. "git fetch") certainly does not say anything about how failure is signaled to the calling program. "git help git" does not have "EXIT CODES" section, and it is assumed that the "common sense" of older generation (gee, this project is more than 18 years old) that exiting with 0 is success and non-zero is failure is shared among its users, which might not be warranted these days.

We could either
 * Be more prescriptive and add "EXIT CODES" section to each and
   every document to describe how we fail in the current code.
or
 * Describe "In general, 0 is success, non-zero is failure, but some
   commands may signal more than that with its non-zero exit codes"
   in "git help git", and add "EXIT CODES" section to the manual
   page of the commands whose exit codes matter (there are a
   handful, like "git diff --exit-code" that explicitly says "1" is
   the signal that it found difference as opposed to it failing).

I'd prefer if community agrees that we should do the latter, but I am OK if the community consensus goes the other way.

If we were to go the former, the task becomes larger but it would be embarrassingly parallelizable. Folks with extra time on their hand can lend their eyes to tackle each command, find what exit code we use in the current code, add "EXIT CODES" section to the documentation, and extend test coverage to ensure their findings will stay unless we deliberately change it in the future.

If we were to go the latter, the task will be significantly smaller. We need to come up with a careful phrasing to add to "git help git" and/or "git help cli" to give the general principle of zero vs non-zero whose exact values are left unspecified and should not be depended upon. We also need to identify the special cases where the exact values have meanings (like the "git diff --exit-code" example above), describe them by adding "EXIT CODES" section to the manual pages of these selected commands, and extend test coverage to ensure these values are kept intact across future changes.

Comments?
Previous: Jeff KingNext: Jeff King
Message 7 of 12 in “upload-pack: fix race condition in error messages”
  1. upload-pack: fix race condition in error messagesDerrick Stolee via GitGitGadget, Aug 10, 2023
  2. Junio C HamanoAug 10, 2023
  3. upload-pack: fix exit code when denying fetch of unreachable object IDPatrick Steinhardt, Aug 16, 2023
  4. Junio C HamanoAug 16, 2023
  5. Junio C HamanoAug 16, 2023
  6. Jeff KingAug 17, 2023
  7. [Leftoverbits] exit code clean-up?Junio C Hamano, Aug 16, 2023
  8. Jeff KingAug 17, 2023
  9. Junio C HamanoAug 17, 2023
  10. Oswald BuddenhagenAug 17, 2023
  11. Junio C HamanoAug 17, 2023
  12. Patrick SteinhardtAug 17, 2023

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.