]> git.ipfire.org Git - thirdparty/git.git/blob - Documentation/technical/api-error-handling.txt
clone: allow "--bare" with "-o"
[thirdparty/git.git] / Documentation / technical / api-error-handling.txt
1 Error reporting in git
2 ======================
3
4 `BUG`, `bug`, `die`, `usage`, `error`, and `warning` report errors of
5 various kinds.
6
7 - `BUG` is for failed internal assertions that should never happen,
8 i.e. a bug in git itself.
9
10 - `bug` (lower-case, not `BUG`) is supposed to be used like `BUG` but
11 prints a "BUG" message instead of calling `abort()`.
12 +
13 A call to `bug()` will then result in a "real" call to the `BUG()`
14 function, either explicitly by invoking `BUG_if_bug()` after call(s)
15 to `bug()`, or implicitly at `exit()` time where we'll check if we
16 encountered any outstanding `bug()` invocations.
17 +
18 If there were no prior calls to `bug()` before invoking `BUG_if_bug()`
19 the latter is a NOOP. The `BUG_if_bug()` function takes the same
20 arguments as `BUG()` itself. Calling `BUG_if_bug()` explicitly isn't
21 necessary, but ensures that we die as soon as possible.
22 +
23 If you know you had prior calls to `bug()` then calling `BUG()` itself
24 is equivalent to calling `BUG_if_bug()`, the latter being a wrapper
25 calling `BUG()` if we've set a flag indicating that we've called
26 `bug()`.
27 +
28 This is for the convenience of APIs who'd like to potentially report
29 more than one "bug", such as the optbug() validation in
30 parse-options.c.
31
32 - `die` is for fatal application errors. It prints a message to
33 the user and exits with status 128.
34
35 - `usage` is for errors in command line usage. After printing its
36 message, it exits with status 129. (See also `usage_with_options`
37 in the link:api-parse-options.html[parse-options API].)
38
39 - `error` is for non-fatal library errors. It prints a message
40 to the user and returns -1 for convenience in signaling the error
41 to the caller.
42
43 - `warning` is for reporting situations that probably should not
44 occur but which the user (and Git) can continue to work around
45 without running into too many problems. Like `error`, it
46 returns -1 after reporting the situation to the caller.
47
48 These reports will be logged via the trace2 facility. See the "error"
49 event in link:api-trace2.txt[trace2 API].
50
51 Customizable error handlers
52 ---------------------------
53
54 The default behavior of `die` and `error` is to write a message to
55 stderr and then exit or return as appropriate. This behavior can be
56 overridden using `set_die_routine` and `set_error_routine`. For
57 example, "git daemon" uses set_die_routine to write the reason `die`
58 was called to syslog before exiting.
59
60 Library errors
61 --------------
62
63 Functions return a negative integer on error. Details beyond that
64 vary from function to function:
65
66 - Some functions return -1 for all errors. Others return a more
67 specific value depending on how the caller might want to react
68 to the error.
69
70 - Some functions report the error to stderr with `error`,
71 while others leave that for the caller to do.
72
73 - errno is not meaningful on return from most functions (except
74 for thin wrappers for system calls).
75
76 Check the function's API documentation to be sure.
77
78 Caller-handled errors
79 ---------------------
80
81 An increasing number of functions take a parameter 'struct strbuf *err'.
82 On error, such functions append a message about what went wrong to the
83 'err' strbuf. The message is meant to be complete enough to be passed
84 to `die` or `error` as-is. For example:
85
86 if (ref_transaction_commit(transaction, &err))
87 die("%s", err.buf);
88
89 The 'err' parameter will be untouched if no error occurred, so multiple
90 function calls can be chained:
91
92 t = ref_transaction_begin(&err);
93 if (!t ||
94 ref_transaction_update(t, "HEAD", ..., &err) ||
95 ret_transaction_commit(t, &err))
96 die("%s", err.buf);
97
98 The 'err' parameter must be a pointer to a valid strbuf. To silence
99 a message, pass a strbuf that is explicitly ignored:
100
101 if (thing_that_can_fail_in_an_ignorable_way(..., &err))
102 /* This failure is okay. */
103 strbuf_reset(&err);