Re: [Leftoverbits] exit code clean-up?

From: Jeff King <peff@peff.net>
Date: Aug 17, 2023, 05:36 UTC
Message-ID: <20230817053627.GC3006160@coredump.intra.peff.net>
In-Reply-To: <xmqqsf8iex5v.fsf_-_@gitster.g>

On Wed, Aug 16, 2023 at 10:04:28AM -0700, Junio C Hamano wrote:

Show 16 quoted lines

> 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.

I left some notes on upload-pack specifically elsewhere in the thread, in which I argue that we should definitely not lock ourselves into its current behavior.

But in the more general sense, yeah, I think that trying to document specific exit codes for each command is a mistake. It is not just "let's find which exit codes they use and document them". I suspect it is a rat's nest of unplanned behaviors that come from unexpected die() calls deep in the stack. We would not necessarily want to make promises about what is happening in those, nor do I think it would even be sensible to find every possible exit.

We _could_ document "128 means something really unexpected happened and we called die() deep in the code". But even that seems misleading to me, as we also die() for everyday shallow things (like "the name you gave is not valid"). The value really means very little in practice, and the biggest reason not to change it is that we know it doesn't conflict with any codes that programs _do_ promise are meaningful (like "1" from "diff --exit-code").

So saying "0 is success, non-zero is failure, and some commands may document specific codes" is the closest thing to the reality of what we as developers know and have planned. (Of course another project is not just to figure out the possible situations/codes but to catalogue and organize them. But that seems like an order of magnitude more work, if not several orders).

-Peff