4 `BUG`, `die`, `usage`, `error`, and `warning` report errors of
7 - `BUG` is for failed internal assertions that should never happen,
8 i.e. a bug in git itself.
10 - `die` is for fatal application errors. It prints a message to
11 the user and exits with status 128.
13 - `usage` is for errors in command line usage. After printing its
14 message, it exits with status 129. (See also `usage_with_options`
15 in the link:api-parse-options.html[parse-options API].)
17 - `error` is for non-fatal library errors. It prints a message
18 to the user and returns -1 for convenience in signaling the error
21 - `warning` is for reporting situations that probably should not
22 occur but which the user (and Git) can continue to work around
23 without running into too many problems. Like `error`, it
24 returns -1 after reporting the situation to the caller.
26 These reports will be logged via the trace2 facility. See the "error"
27 event in link:api-trace2.txt[trace2 API].
29 Customizable error handlers
30 ---------------------------
32 The default behavior of `die` and `error` is to write a message to
33 stderr and then exit or return as appropriate. This behavior can be
34 overridden using `set_die_routine` and `set_error_routine`. For
35 example, "git daemon" uses set_die_routine to write the reason `die`
36 was called to syslog before exiting.
41 Functions return a negative integer on error. Details beyond that
42 vary from function to function:
44 - Some functions return -1 for all errors. Others return a more
45 specific value depending on how the caller might want to react
48 - Some functions report the error to stderr with `error`,
49 while others leave that for the caller to do.
51 - errno is not meaningful on return from most functions (except
52 for thin wrappers for system calls).
54 Check the function's API documentation to be sure.
59 An increasing number of functions take a parameter 'struct strbuf *err'.
60 On error, such functions append a message about what went wrong to the
61 'err' strbuf. The message is meant to be complete enough to be passed
62 to `die` or `error` as-is. For example:
64 if (ref_transaction_commit(transaction, &err))
67 The 'err' parameter will be untouched if no error occurred, so multiple
68 function calls can be chained:
70 t = ref_transaction_begin(&err);
72 ref_transaction_update(t, "HEAD", ..., &err) ||
73 ret_transaction_commit(t, &err))
76 The 'err' parameter must be a pointer to a valid strbuf. To silence
77 a message, pass a strbuf that is explicitly ignored:
79 if (thing_that_can_fail_in_an_ignorable_way(..., &err))
80 /* This failure is okay. */