projects / thirdparty / git.git / blame
| Commit | Line | Data |
|---|---|---|
| 1f23cfe0 JN |
1 | Error reporting in git |
| 2 | ====================== | |
| 3 | ||
| 4 | `die`, `usage`, `error`, and `warning` report errors of various | |
| 5 | kinds. | |
| 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 | ||
| 23 | Customizable error handlers | |
| 24 | --------------------------- | |
| 25 | ||
| 26 | The default behavior of `die` and `error` is to write a message to | |
| 27 | stderr and then exit or return as appropriate. This behavior can be | |
| 28 | overridden using `set_die_routine` and `set_error_routine`. For | |
| 29 | example, "git daemon" uses set_die_routine to write the reason `die` | |
| 30 | was called to syslog before exiting. | |
| 31 | ||
| 32 | Library errors | |
| 33 | -------------- | |
| 34 | ||
| 35 | Functions return a negative integer on error. Details beyond that | |
| 36 | vary 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 | ||
| 48 | Check the function's API documentation to be sure. | |
| 49 | ||
| 50 | Caller-handled errors | |
| 51 | --------------------- | |
| 52 | ||
| 53 | An increasing number of functions take a parameter 'struct strbuf *err'. | |
| 54 | On 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 | |
| 56 | to `die` or `error` as-is. For example: | |
| 57 | ||
| 58 | if (ref_transaction_commit(transaction, &err)) | |
| 59 | die("%s", err.buf); | |
| 60 | ||
| 39d5bef5 | 61 | The 'err' parameter will be untouched if no error occurred, so multiple |
| 1f23cfe0 JN |
62 | function 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 | ||
| 70 | The 'err' parameter must be a pointer to a valid strbuf. To silence | |
| 71 | a 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); |