BUG, bug, die, usage, error, warning は、さまざまな種類のエラーを報告します。

  • BUG は、決して起こらないはずの失敗した内部アサーション、つまりgit自体のバグのためのものです。

  • bug (小文字。 BUG ではない) は BUG のように使用されますが、abort() を呼び出す代わりに「BUG」メッセージを出力します。

    bug() への呼び出しは、 bug() への呼び出しの後に BUG_if_bug() を呼び出すことによって明示的に、または未解決の bug() 呼び出しに遭遇したかどうかを確認する exit() 時に暗黙的に、 BUG() 関数への「実際の」呼び出しになります。

    BUG_if_bug() を呼び出す前に bug() への呼び出しがなかった場合、 後者は NOOP です。 BUG_if_bug() 関数は BUG() 自体と同じ引数を取ります。 BUG_if_bug() を明示的に呼び出す必要はありませんが、 できるだけ早くプログラムを止める(die)ことを保証します。

    以前に bug() を呼び出したことがあることがわかっている場合、 BUG() 自体を呼び出すことは、BUG_if_bug() を呼び出すことと同等です。 後者は、 BUG() を呼び出したことを示すフラグを設定した場合、 BUG() を呼び出すラッパーです。

    これは、 parse-options.c の optbug() 検証(validation)など、 複数の「バグ」を報告する可能性がある API の便宜のためです。

  • die は致命的なアプリケーションエラー用です。 ユーザーにメッセージを出力し、ステータス128で終了します。

  • usage は、コマンドラインの使用法のエラー用です。 メッセージを出力した後、ステータス129で終了します(parse-options API の usage_with_options も参照してください)。

  • error は、致命的ではないライブラリエラー用です。 ユーザーにメッセージを出力し、呼び出し元にエラーを通知するのに便利なように -1 を返します。

  • warning は、おそらく発生しないはずの状況を報告するためのものですが、ユーザー(およびGit)はあまり多くの問題に遭遇することなく回避を続けることができます。 error と同様に、呼び出し元に状況を報告した後、 -1 を返します。

これらのレポートは、trace2機能を介してログに記録されます。 trace2 API の「error」イベントを参照してください。

Customizable error handlers

die と error のデフォルトの動作は、stderrにメッセージを書き込んでから、必要に応じて終了(exit)または戻ることです。 この振る舞いは、 set_die_routine と set_error_routine を使用してオーバーライドできます。 例えば、 git daemon は set_die_routine を使って、 die が呼ばれた理由を syslog に書き込んでから終了するようにしています。

Library errors

各関数はエラー時に負の整数を返します。それ以外の詳細は機能ごとに異なります:

  • 一部の関数は、すべてのエラーに対して -1 を返します。 それ以外の関数は、呼び出し元がエラーにどのように反応したいかに応じて、より具体的な値を返します。

  • 一部の関数はエラーを error でstderrに報告しますが、それ以外の関数はそれを呼び出し元に任せます。

  • errno は、ほとんどの関数から戻ったときに意味がありません(システムコールの薄いラッパー(thin wrappers)を除く)。

各関数のAPIドキュメントを確認してください。

Caller-handled errors

ますます多くの関数がパラメータ struct strbuf *err を取るようになっています。エラーの場合、そのような関数は、 err strbufに何がうまくいかなかったかについてのメッセージを追加します。 メッセージは、そのまま die または error に渡されるのに十分なほど完全であることを意図しています。 例えば:

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

エラーが発生しなかった場合、 err パラメーターは変更されないため、複数の関数呼び出しを連鎖させることができます:

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

err パラメーターは、有効なstrbufへのポインターでなければなりません。 メッセージを黙らせるには、明示的に無視されるstrbufを渡します:

if (thing_that_can_fail_in_an_ignorable_way(..., &err))
        /* This failure is okay. */
        strbuf_reset(&err);