git.oblomov.eu Git - git/blob - Documentation/technical/api-error-handling.txt

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