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