From: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>
Date: Thu, 17 Aug 2023 09:24:26 GMT
Subject: Re: [Leftoverbits] exit code clean-up?
Message-ID: <ZN3nSsGOHMDQZ438@ugly>
In-Reply-To: <xmqqsf8iex5v.fsf_-_@gitster.g>

On Wed, Aug 16, 2023 at 10:04:28AM -0700, Junio C Hamano wrote:
>"git help git" does not have "EXIT CODES" section, and it is assumed 
>that the "common sense" of older generation [...] that exiting with 0 
>is success and non-zero is failure is shared among its users, which 
>might not be warranted these days.
>
well, that's actually a standard (exit(3) has things to say about it), 
and given how shell scripts treat exit codes, there is no wiggle room 
here. just about every shell intro tutorial explains it.

>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 go with the second, with some minor modifications:
- 1 is the by far most common non-zero error code (and it matches 
   EXIT_FAILURE on all relevant systems), so it's ok to state that. it 
   may be wise to actually check that commands don't deviate from it 
   needlessly.
- the canonical name of the section appears to be "EXIT STATUS"

regards