Subject: [Leftoverbits] exit code clean-up?

From: Junio C Hamano <[email-masked]>
Date: Wed, 16 Aug 2023 10:04:28 -0700

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?