Merge branch 'ws/grep-quiet-no-pager'
[git] / Documentation / technical / api-error-handling.txt
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
61 The 'err' parameter will be untouched if no error occured, so multiple
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);