From d3f9c05312b28e7a5b55b229f289625119b09314 Mon Sep 17 00:00:00 2001
From: Michael Terry <mike@mterry.name>
Date: Sat, 3 Aug 2024 16:20:56 -0400
Subject: [PATCH] docs: update scripting documentation
---
doc/075_scripting.rst | 51 +++++++++++++++++++++++++++++++++----------
1 file changed, 39 insertions(+), 12 deletions(-)
diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst
index fa7fa1b6e..90bf111d7 100644
--- a/doc/075_scripting.rst
+++ b/doc/075_scripting.rst
@@ -83,12 +83,33 @@ JSON output of most restic commands are documented here.
list of allowed values is documented may be extended at any time.
+Exit errors
+-----------
+
+Fatal errors will result in a final JSON message on ``stderr`` before the process exits.
+It will hold the error message and the exit code.
+
+.. note::
+ Some errors cannot be caught and reported this way,
+ such as Go runtime errors or command line parsing errors.
+
++----------------------+-------------------------------------------+
+| ``message_type`` | Always "exit_error" |
++----------------------+-------------------------------------------+
+| ``code`` | Exit code (see above chart) |
++----------------------+-------------------------------------------+
+| ``error`` | Error message |
++----------------------+-------------------------------------------+
+
Output formats
--------------
-Currently only the output on ``stdout`` is JSON formatted. Errors printed on ``stderr``
-are still printed as plain text messages. The generated JSON output uses one of the
-following two formats.
+Commands print their main JSON output on ``stdout``.
+The generated JSON output uses one of the following two formats.
+
+.. note::
+ Not all messages and errors have been converted to JSON yet.
+ Feel free to submit a pull request!
Single JSON document
^^^^^^^^^^^^^^^^^^^^
@@ -136,6 +157,8 @@ Status
Error
^^^^^
+These errors are printed on ``stderr``.
+
+----------------------+-------------------------------------------+
| ``message_type`` | Always "error" |
+----------------------+-------------------------------------------+
@@ -542,6 +565,8 @@ Status
Error
^^^^^
+These errors are printed on ``stderr``.
+
+----------------------+-------------------------------------------+
| ``message_type`` | Always "error" |
+----------------------+-------------------------------------------+
@@ -691,12 +716,14 @@ version
The version command returns a single JSON object.
-+----------------+--------------------+
-| ``version`` | restic version |
-+----------------+--------------------+
-| ``go_version`` | Go compile version |
-+----------------+--------------------+
-| ``go_os`` | Go OS |
-+----------------+--------------------+
-| ``go_arch`` | Go architecture |
-+----------------+--------------------+
++------------------+--------------------+
+| ``message_type`` | Always "version" |
++------------------+--------------------+
+| ``version`` | restic version |
++------------------+--------------------+
+| ``go_version`` | Go compile version |
++------------------+--------------------+
+| ``go_os`` | Go OS |
++------------------+--------------------+
+| ``go_arch`` | Go architecture |
++------------------+--------------------+