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?
