4 `BUG`, `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 - `bug` (lower-case, not `BUG`) is supposed to be used like `BUG` but
11 prints a "BUG" message instead of calling `abort()`.
13 A call to `bug()` will then result in a "real" call to the `BUG()`
14 function, either explicitly by invoking `BUG_if_bug()` after call(s)
15 to `bug()`, or implicitly at `exit()` time where we'll check if we
16 encountered any outstanding `bug()` invocations.
18 If there were no prior calls to `bug()` before invoking `BUG_if_bug()`
19 the latter is a NOOP. The `BUG_if_bug()` function takes the same
20 arguments as `BUG()` itself. Calling `BUG_if_bug()` explicitly isn't
21 necessary, but ensures that we die as soon as possible.
23 If you know you had prior calls to `bug()` then calling `BUG()` itself
24 is equivalent to calling `BUG_if_bug()`, the latter being a wrapper
25 calling `BUG()` if we've set a flag indicating that we've called
28 This is for the convenience of APIs who'd like to potentially report
29 more than one "bug", such as the optbug() validation in
32 - `die` is for fatal application errors. It prints a message to
33 the user and exits with status 128.
35 - `usage` is for errors in command line usage. After printing its
36 message, it exits with status 129. (See also `usage_with_options`
37 in the link:api-parse-options.html[parse-options API].)
39 - `error` is for non-fatal library errors. It prints a message
40 to the user and returns -1 for convenience in signaling the error
43 - `warning` is for reporting situations that probably should not
44 occur but which the user (and Git) can continue to work around
45 without running into too many problems. Like `error`, it
46 returns -1 after reporting the situation to the caller.
48 These reports will be logged via the trace2 facility. See the "error"
49 event in link:api-trace2.txt[trace2 API].
51 Customizable error handlers
52 ---------------------------
54 The default behavior of `die` and `error` is to write a message to
55 stderr and then exit or return as appropriate. This behavior can be
56 overridden using `set_die_routine` and `set_error_routine`. For
57 example, "git daemon" uses set_die_routine to write the reason `die`
58 was called to syslog before exiting.
63 Functions return a negative integer on error. Details beyond that
64 vary from function to function:
66 - Some functions return -1 for all errors. Others return a more
67 specific value depending on how the caller might want to react
70 - Some functions report the error to stderr with `error`,
71 while others leave that for the caller to do.
73 - errno is not meaningful on return from most functions (except
74 for thin wrappers for system calls).
76 Check the function's API documentation to be sure.
81 An increasing number of functions take a parameter 'struct strbuf *err'.
82 On error, such functions append a message about what went wrong to the
83 'err' strbuf. The message is meant to be complete enough to be passed
84 to `die` or `error` as-is. For example:
86 if (ref_transaction_commit(transaction, &err))
89 The 'err' parameter will be untouched if no error occurred, so multiple
90 function calls can be chained:
92 t = ref_transaction_begin(&err);
94 ref_transaction_update(t, "HEAD", ..., &err) ||
95 ret_transaction_commit(t, &err))
98 The 'err' parameter must be a pointer to a valid strbuf. To silence
99 a message, pass a strbuf that is explicitly ignored:
101 if (thing_that_can_fail_in_an_ignorable_way(..., &err))
102 /* This failure is okay. */