[thirdparty/git.git] / Documentation / technical / api-error-handling.txt

Error reporting in git
======================

`BUG`, `die`, `usage`, `error`, and `warning` report errors of
various kinds.

- `BUG` is for failed internal assertions that should never happen,
  i.e. a bug in git itself.

- `die` is for fatal application errors.  It prints a message to
  the user and exits with status 128.

- `usage` is for errors in command line usage.  After printing its
  message, it exits with status 129.  (See also `usage_with_options`
  in the link:api-parse-options.html[parse-options API].)

- `error` is for non-fatal library errors.  It prints a message
  to the user and returns -1 for convenience in signaling the error
  to the caller.

- `warning` is for reporting situations that probably should not
  occur but which the user (and Git) can continue to work around
  without running into too many problems.  Like `error`, it
  returns -1 after reporting the situation to the caller.

These reports will be logged via the trace2 facility. See the "error"
event in link:api-trace2.txt[trace2 API].

Customizable error handlers
---------------------------

The default behavior of `die` and `error` is to write a message to
stderr and then exit or return as appropriate.  This behavior can be
overridden using `set_die_routine` and `set_error_routine`.  For
example, "git daemon" uses set_die_routine to write the reason `die`
was called to syslog before exiting.

Library errors
--------------

Functions return a negative integer on error.  Details beyond that
vary from function to function:

- Some functions return -1 for all errors.  Others return a more
  specific value depending on how the caller might want to react
  to the error.

- Some functions report the error to stderr with `error`,
  while others leave that for the caller to do.

- errno is not meaningful on return from most functions (except
  for thin wrappers for system calls).

Check the function's API documentation to be sure.

Caller-handled errors
---------------------

An increasing number of functions take a parameter 'struct strbuf *err'.
On error, such functions append a message about what went wrong to the
'err' strbuf.  The message is meant to be complete enough to be passed
to `die` or `error` as-is.  For example:

	if (ref_transaction_commit(transaction, &err))
		die("%s", err.buf);

The 'err' parameter will be untouched if no error occurred, so multiple
function calls can be chained:

	t = ref_transaction_begin(&err);
	if (!t ||
	    ref_transaction_update(t, "HEAD", ..., &err) ||
	    ret_transaction_commit(t, &err))
		die("%s", err.buf);

The 'err' parameter must be a pointer to a valid strbuf.  To silence
a message, pass a strbuf that is explicitly ignored:

	if (thing_that_can_fail_in_an_ignorable_way(..., &err))
		/* This failure is okay. */
		strbuf_reset(&err);
Commit	Line	Data
1f23cfe0 JN	1	Error reporting in git
	2	======================
	3
4bf0c6f3 ÆAB	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.
1f23cfe0 JN	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
f6d25d78 ÆAB	26	These reports will be logged via the trace2 facility. See the "error"
	27	event in link:api-trace2.txt[trace2 API].
	28
1f23cfe0 JN	29	Customizable error handlers
	30	---------------------------
	31
	32	The default behavior of `die` and `error` is to write a message to
	33	stderr and then exit or return as appropriate. This behavior can be
	34	overridden using `set_die_routine` and `set_error_routine`. For
	35	example, "git daemon" uses set_die_routine to write the reason `die`
	36	was called to syslog before exiting.
	37
	38	Library errors
	39	--------------
	40
	41	Functions return a negative integer on error. Details beyond that
	42	vary from function to function:
	43
	44	- Some functions return -1 for all errors. Others return a more
	45	specific value depending on how the caller might want to react
	46	to the error.
	47
	48	- Some functions report the error to stderr with `error`,
	49	while others leave that for the caller to do.
	50
	51	- errno is not meaningful on return from most functions (except
	52	for thin wrappers for system calls).
	53
	54	Check the function's API documentation to be sure.
	55
	56	Caller-handled errors
	57	---------------------
	58
	59	An increasing number of functions take a parameter 'struct strbuf *err'.
	60	On error, such functions append a message about what went wrong to the
	61	'err' strbuf. The message is meant to be complete enough to be passed
	62	to `die` or `error` as-is. For example:
	63
	64	if (ref_transaction_commit(transaction, &err))
	65	die("%s", err.buf);
	66
39d5bef5	67	The 'err' parameter will be untouched if no error occurred, so multiple
1f23cfe0 JN	68	function calls can be chained:
	69
	70	t = ref_transaction_begin(&err);
	71	if (!t \|\|
	72	ref_transaction_update(t, "HEAD", ..., &err) \|\|
	73	ret_transaction_commit(t, &err))
	74	die("%s", err.buf);
	75
	76	The 'err' parameter must be a pointer to a valid strbuf. To silence
	77	a message, pass a strbuf that is explicitly ignored:
	78
	79	if (thing_that_can_fail_in_an_ignorable_way(..., &err))
	80	/* This failure is okay. */
	81	strbuf_reset(&err);