]>
Commit | Line | Data |
---|---|---|
1 | Error reporting in git | |
2 | ====================== | |
3 | ||
4 | `BUG`, `bug`, `die`, `usage`, `error`, and `warning` report errors of | |
5 | various kinds. | |
6 | ||
7 | - `BUG` is for failed internal assertions that should never happen, | |
8 | i.e. a bug in git itself. | |
9 | ||
10 | - `bug` (lower-case, not `BUG`) is supposed to be used like `BUG` but | |
11 | prints a "BUG" message instead of calling `abort()`. | |
12 | + | |
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. | |
17 | + | |
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. | |
22 | + | |
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 | |
26 | `bug()`. | |
27 | + | |
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 | |
30 | parse-options.c. | |
31 | ||
32 | - `die` is for fatal application errors. It prints a message to | |
33 | the user and exits with status 128. | |
34 | ||
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].) | |
38 | ||
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 | |
41 | to the caller. | |
42 | ||
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. | |
47 | ||
48 | These reports will be logged via the trace2 facility. See the "error" | |
49 | event in link:api-trace2.txt[trace2 API]. | |
50 | ||
51 | Customizable error handlers | |
52 | --------------------------- | |
53 | ||
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. | |
59 | ||
60 | Library errors | |
61 | -------------- | |
62 | ||
63 | Functions return a negative integer on error. Details beyond that | |
64 | vary from function to function: | |
65 | ||
66 | - Some functions return -1 for all errors. Others return a more | |
67 | specific value depending on how the caller might want to react | |
68 | to the error. | |
69 | ||
70 | - Some functions report the error to stderr with `error`, | |
71 | while others leave that for the caller to do. | |
72 | ||
73 | - errno is not meaningful on return from most functions (except | |
74 | for thin wrappers for system calls). | |
75 | ||
76 | Check the function's API documentation to be sure. | |
77 | ||
78 | Caller-handled errors | |
79 | --------------------- | |
80 | ||
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: | |
85 | ||
86 | if (ref_transaction_commit(transaction, &err)) | |
87 | die("%s", err.buf); | |
88 | ||
89 | The 'err' parameter will be untouched if no error occurred, so multiple | |
90 | function calls can be chained: | |
91 | ||
92 | t = ref_transaction_begin(&err); | |
93 | if (!t || | |
94 | ref_transaction_update(t, "HEAD", ..., &err) || | |
95 | ret_transaction_commit(t, &err)) | |
96 | die("%s", err.buf); | |
97 | ||
98 | The 'err' parameter must be a pointer to a valid strbuf. To silence | |
99 | a message, pass a strbuf that is explicitly ignored: | |
100 | ||
101 | if (thing_that_can_fail_in_an_ignorable_way(..., &err)) | |
102 | /* This failure is okay. */ | |
103 | strbuf_reset(&err); |