Error reporting in git ====================== `die`, `usage`, `error`, and `warning` report errors of various kinds. - `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. 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);