f6d25d7878
Correct documentation added ine544221d97(trace2: Documentation/technical/api-trace2.txt, 2019-02-22) to state that calling BUG() also emits an "error" event. Seeee4512ed48(trace2: create new combined trace facility, 2019-02-22) for the initial implementation. The BUG() function did not emit an event then however, that was only changed later in0a9dde4a04(usage: trace2 BUG() invocations, 2021-02-05), that commit changed the code, but didn't update any of the docs. Let's also add a cross-reference from api-error-handling.txt. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
82 lines
2.7 KiB
Plaintext
82 lines
2.7 KiB
Plaintext
Error reporting in git
|
|
======================
|
|
|
|
`BUG`, `die`, `usage`, `error`, and `warning` report errors of
|
|
various kinds.
|
|
|
|
- `BUG` is for failed internal assertions that should never happen,
|
|
i.e. a bug in git itself.
|
|
|
|
- `die` is for fatal application errors. It prints a message to
|
|
the user and exits with status 128.
|
|
|
|
- `usage` is for errors in command line usage. After printing its
|
|
message, it exits with status 129. (See also `usage_with_options`
|
|
in the link:api-parse-options.html[parse-options API].)
|
|
|
|
- `error` is for non-fatal library errors. It prints a message
|
|
to the user and returns -1 for convenience in signaling the error
|
|
to the caller.
|
|
|
|
- `warning` is for reporting situations that probably should not
|
|
occur but which the user (and Git) can continue to work around
|
|
without running into too many problems. Like `error`, it
|
|
returns -1 after reporting the situation to the caller.
|
|
|
|
These reports will be logged via the trace2 facility. See the "error"
|
|
event in link:api-trace2.txt[trace2 API].
|
|
|
|
Customizable error handlers
|
|
---------------------------
|
|
|
|
The default behavior of `die` and `error` is to write a message to
|
|
stderr and then exit or return as appropriate. This behavior can be
|
|
overridden using `set_die_routine` and `set_error_routine`. For
|
|
example, "git daemon" uses set_die_routine to write the reason `die`
|
|
was called to syslog before exiting.
|
|
|
|
Library errors
|
|
--------------
|
|
|
|
Functions return a negative integer on error. Details beyond that
|
|
vary from function to function:
|
|
|
|
- Some functions return -1 for all errors. Others return a more
|
|
specific value depending on how the caller might want to react
|
|
to the error.
|
|
|
|
- Some functions report the error to stderr with `error`,
|
|
while others leave that for the caller to do.
|
|
|
|
- errno is not meaningful on return from most functions (except
|
|
for thin wrappers for system calls).
|
|
|
|
Check the function's API documentation to be sure.
|
|
|
|
Caller-handled errors
|
|
---------------------
|
|
|
|
An increasing number of functions take a parameter 'struct strbuf *err'.
|
|
On error, such functions append a message about what went wrong to the
|
|
'err' strbuf. The message is meant to be complete enough to be passed
|
|
to `die` or `error` as-is. For example:
|
|
|
|
if (ref_transaction_commit(transaction, &err))
|
|
die("%s", err.buf);
|
|
|
|
The 'err' parameter will be untouched if no error occurred, so multiple
|
|
function calls can be chained:
|
|
|
|
t = ref_transaction_begin(&err);
|
|
if (!t ||
|
|
ref_transaction_update(t, "HEAD", ..., &err) ||
|
|
ret_transaction_commit(t, &err))
|
|
die("%s", err.buf);
|
|
|
|
The 'err' parameter must be a pointer to a valid strbuf. To silence
|
|
a message, pass a strbuf that is explicitly ignored:
|
|
|
|
if (thing_that_can_fail_in_an_ignorable_way(..., &err))
|
|
/* This failure is okay. */
|
|
strbuf_reset(&err);
|