Re: What are cherry-pick's exit codes?

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Thu, Dec 01 2022, Sean Allred wrote:

> Hi folks,
>
> We're developing some internal tooling wrapping git-cherry-pick and need
> to be able to distinguish its different error codes. Problem is: these
> exit codes don't seem to be documented in git-cherry-pick.txt.
>
> Looking at the source, I found myself down the rabbit-hole very quickly.
> I'm not too familiar with the coding patterns quite yet -- but I'm
> pretty sure I eventually found myself redirected to git-commit in one
> case. At that point, I thought it better to ask here.

This is definitely worth doing, and there's a bit of a rabbit hole here,
so it'l also good you asked.

> I'd like to document these exit codes in the manpage and I'm more than
> happy to submit the patch, but I thought I'd confirm my understanding
> first since it's based purely on reading the cherry-pick tests:
>
> Exit code:
>
>   - 0: success, sequencer complete -- no conflicts
>
>   - 1: 'success', sequencer incomplete -- conflicts encountered

In general I think you'd do well to follow the template of what I did in
9144ba4cf52 (remote: add meaningful exit code on missing/existing,
2020-10-27).

In particular, I don't think we should exhaustively document exit codes
for a given command, as we really have a hard time controlling all the
possible values.

Rather, we should define specific non-zero values as having specific
meanings, as I did with "git remote" in that commit.

We'd also ideally leave "exit(1)" alone, and if we need to disambiguate
it start with "exit(2)", but maybe it's easy to make it unambiguous in
this case, or it's already unambiguous...


>   - 127: fatal -- lots of reasons -- I'm guessing this is value for the
>     'return -1' and 'return error(...)' statements speckled throughout
>     the code, but it's been a long time since I cared about two's
>     complement so I may be wrong here.

If it's "return -1" you generally end up with 255 in your shell,
although that's unportable both for the C language, and for POSIX.

See 19d75948ef7 (common-main.c: move non-trace2 exit() behavior out of
trace2.c, 2022-06-02) for some code dealing with that (where we fake up
the -1 to 255, for logging).

But from looking at cmd_cherry_pick() we catch any <0 return values and
die() on them, but maybe we exit() elsewhere? Do you have an example of
these.

>   - 128: fatal -- sequence is interrupted, possibly due to some other
>     fatal error, e.g., 'commit doesn't exist' or 'mainline parent number
>     doesn't exist'
>
>   - 129: fatal -- there was nothing to cherry-pick at all (e.g. empty
>     range)

I think as in 9144ba4cf52 (remote: add meaningful exit code on
missing/existing, 2020-10-27) it's good to just leave these
undocumented.

We typically return these when we invoke die() or usage_with_options()
(or similar).

So, if we are documenting them (which would be a good change, as an
aside) that probably belongs in gitcli(7), we could then reference that
from other man pages.

> I'm reasonably confident about 0/1 just anecdotally -- I'm less sure
> about everything else.
>
> Obviously the actual text put in the manpage should be friendlier and
> possibly vaguer for clarity (paradoxical, perhaps, but it seems more
> direct to say '0 for success, 1 for conflicts, and anything else is a
> fatal error'), but I wanted to make sure that I have an actually-
> accurate understanding rather than something only surface-level.
>
> Two questions:
>
>   1. Are the exit codes actually documented somewhere already that
>      should simply be linked from git-cherry-pick.txt?

No, just when we promise specific codes for specific
commands. E.g. git-remote, git-config etc. come to mind.

>   2. If not, is the above listing the exit codes accurate and complete?

I don't know, but skimming the code I don't see the "return 1", unless
by the above " - 1" you mean "minus one", i.e. 255.

I.e. cmd_cherry_pick() calls run_sequencer(), which on error seems to
return -1 for most things, which we then coerce to that die().

But I haven't looked in much detail, so...