| 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); |