Autogenerated HTML docs for v2.36.1-428-g5699e

4 files changed, 51 insertions, 8 deletions

diff --git a/technical/api-error-handling.html b/technical/api-error-handling.html
index 4f8e32871..fb98bca76 100644
--- a/technical/api-error-handling.html
+++ b/technical/api-error-handling.html
@@ -739,7 +739,7 @@ asciidoc.install();
 <div id="content">

 <div id="preamble">

 <div class="sectionbody">

-<div class="paragraph"><p><code>BUG</code>, <code>die</code>, <code>usage</code>, <code>error</code>, and <code>warning</code> report errors of

+<div class="paragraph"><p><code>BUG</code>, <code>bug</code>, <code>die</code>, <code>usage</code>, <code>error</code>, and <code>warning</code> report errors of

 various kinds.</p></div>

 <div class="ulist"><ul>

 <li>

@@ -750,6 +750,27 @@ various kinds.</p></div>
 </li>

 <li>

 <p>

+<code>bug</code> (lower-case, not <code>BUG</code>) is supposed to be used like <code>BUG</code> but

+  prints a "BUG" message instead of calling <code>abort()</code>.

+</p>

+<div class="paragraph"><p>A call to <code>bug()</code> will then result in a "real" call to the <code>BUG()</code>

+function, either explicitly by invoking <code>BUG_if_bug()</code> after call(s)

+to <code>bug()</code>, or implicitly at <code>exit()</code> time where we&#8217;ll check if we

+encountered any outstanding <code>bug()</code> invocations.</p></div>

+<div class="paragraph"><p>If there were no prior calls to <code>bug()</code> before invoking <code>BUG_if_bug()</code>

+the latter is a NOOP. The <code>BUG_if_bug()</code> function takes the same

+arguments as <code>BUG()</code> itself. Calling <code>BUG_if_bug()</code> explicitly isn&#8217;t

+necessary, but ensures that we die as soon as possible.</p></div>

+<div class="paragraph"><p>If you know you had prior calls to <code>bug()</code> then calling <code>BUG()</code> itself

+is equivalent to calling <code>BUG_if_bug()</code>, the latter being a wrapper

+calling <code>BUG()</code> if we&#8217;ve set a flag indicating that we&#8217;ve called

+<code>bug()</code>.</p></div>

+<div class="paragraph"><p>This is for the convenience of APIs who&#8217;d like to potentially report

+more than one "bug", such as the optbug() validation in

+parse-options.c.</p></div>

+</li>

+<li>

+<p>

 <code>die</code> is for fatal application errors.  It prints a message to

   the user and exits with status 128.

 </p>

@@ -857,7 +878,7 @@ a message, pass a strbuf that is explicitly ignored:</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-04-29 23:16:11 PDT

+ 2022-06-10 15:52:52 PDT

 </div>

 </div>

 </body>

diff --git a/technical/api-error-handling.txt b/technical/api-error-handling.txt
index 8be4f4d0d..70bf1d3e5 100644
--- a/technical/api-error-handling.txt
+++ b/technical/api-error-handling.txt
@@ -1,12 +1,34 @@
 Error reporting in git
 ======================
 
-`BUG`, `die`, `usage`, `error`, and `warning` report errors of
+`BUG`, `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.
 
+- `bug` (lower-case, not `BUG`) is supposed to be used like `BUG` but
+  prints a "BUG" message instead of calling `abort()`.
++
+A call to `bug()` will then result in a "real" call to the `BUG()`
+function, either explicitly by invoking `BUG_if_bug()` after call(s)
+to `bug()`, or implicitly at `exit()` time where we'll check if we
+encountered any outstanding `bug()` invocations.
++
+If there were no prior calls to `bug()` before invoking `BUG_if_bug()`
+the latter is a NOOP. The `BUG_if_bug()` function takes the same
+arguments as `BUG()` itself. Calling `BUG_if_bug()` explicitly isn't
+necessary, but ensures that we die as soon as possible.
++
+If you know you had prior calls to `bug()` then calling `BUG()` itself
+is equivalent to calling `BUG_if_bug()`, the latter being a wrapper
+calling `BUG()` if we've set a flag indicating that we've called
+`bug()`.
++
+This is for the convenience of APIs who'd like to potentially report
+more than one "bug", such as the optbug() validation in
+parse-options.c.
+
 - `die` is for fatal application errors.  It prints a message to
   the user and exits with status 128.
 
diff --git a/technical/api-trace2.html b/technical/api-trace2.html
index 27cf593fc..1098a47c6 100644
--- a/technical/api-trace2.html
+++ b/technical/api-trace2.html
@@ -1337,8 +1337,8 @@ completed.)</p></div>
 </dt>

 <dd>

 <p>

-        This event is emitted when one of the <code>BUG()</code>, <code>error()</code>, <code>die()</code>,

-        <code>warning()</code>, or <code>usage()</code> functions are called.

+        This event is emitted when one of the <code>BUG()</code>, <code>bug()</code>, <code>error()</code>,

+        <code>die()</code>, <code>warning()</code>, or <code>usage()</code> functions are called.

 </p>

 <div class="listingblock">

 <div class="content">

@@ -2216,7 +2216,7 @@ Trace2 targets (and convert &lt;key&gt; to a "category").
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2022-05-20 17:49:41 PDT

+ 2022-06-10 15:52:52 PDT

 </div>

 </div>

 </body>

diff --git a/technical/api-trace2.txt b/technical/api-trace2.txt
index f4a8a6908..77a150b30 100644
--- a/technical/api-trace2.txt
+++ b/technical/api-trace2.txt
@@ -465,8 +465,8 @@ completed.)
 ------------
 
 `"error"`::
-	This event is emitted when one of the `BUG()`, `error()`, `die()`,
-	`warning()`, or `usage()` functions are called.
+	This event is emitted when one of the `BUG()`, `bug()`, `error()`,
+	`die()`, `warning()`, or `usage()` functions are called.
 +
 ------------
 {