From d3f9c05312b28e7a5b55b229f289625119b09314 Mon Sep 17 00:00:00 2001 From: Michael Terry 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 | ++------------------+--------------------+