1Error reporting in git 2====================== 3 4`die`, `usage`, `error`, and `warning` report errors of various 5kinds. 6 7- `die` is for fatal application errors. It prints a message to 8 the user and exits with status 128. 9 10- `usage` is for errors in command line usage. After printing its 11 message, it exits with status 129. (See also `usage_with_options` 12 in the link:api-parse-options.html[parse-options API].) 13 14- `error` is for non-fatal library errors. It prints a message 15 to the user and returns -1 for convenience in signaling the error 16 to the caller. 17 18- `warning` is for reporting situations that probably should not 19 occur but which the user (and Git) can continue to work around 20 without running into too many problems. Like `error`, it 21 returns -1 after reporting the situation to the caller. 22 23Customizable error handlers 24--------------------------- 25 26The default behavior of `die` and `error` is to write a message to 27stderr and then exit or return as appropriate. This behavior can be 28overridden using `set_die_routine` and `set_error_routine`. For 29example, "git daemon" uses set_die_routine to write the reason `die` 30was called to syslog before exiting. 31 32Library errors 33-------------- 34 35Functions return a negative integer on error. Details beyond that 36vary from function to function: 37 38- Some functions return -1 for all errors. Others return a more 39 specific value depending on how the caller might want to react 40 to the error. 41 42- Some functions report the error to stderr with `error`, 43 while others leave that for the caller to do. 44 45- errno is not meaningful on return from most functions (except 46 for thin wrappers for system calls). 47 48Check the function's API documentation to be sure. 49 50Caller-handled errors 51--------------------- 52 53An increasing number of functions take a parameter 'struct strbuf *err'. 54On error, such functions append a message about what went wrong to the 55'err' strbuf. The message is meant to be complete enough to be passed 56to `die` or `error` as-is. For example: 57 58 if (ref_transaction_commit(transaction, &err)) 59 die("%s", err.buf); 60 61The 'err' parameter will be untouched if no error occurred, so multiple 62function calls can be chained: 63 64 t = ref_transaction_begin(&err); 65 if (!t || 66 ref_transaction_update(t, "HEAD", ..., &err) || 67 ret_transaction_commit(t, &err)) 68 die("%s", err.buf); 69 70The 'err' parameter must be a pointer to a valid strbuf. To silence 71a message, pass a strbuf that is explicitly ignored: 72 73 if (thing_that_can_fail_in_an_ignorable_way(..., &err)) 74 /* This failure is okay. */ 75 strbuf_reset(&err);