MirrorSave
/
restic
mirror of https://github.com/restic/restic.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: reformat scripting tables

This commit is contained in:
Michael Eischer 2025-02-06 19:46:41 +01:00
parent da47967316
commit 59b7007534
1 changed files with 224 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

298
doc/075_scripting.rst
View File

@ -97,13 +97,13 @@ It will hold the error message and the exit code.
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) |
+----------------------+-------------------------------------------+
+------------------+-----------------------------+
| ``message`` | Error message |
+----------------------+-------------------------------------------+
+------------------+-----------------------------+
Output formats
--------------
@ -136,105 +136,105 @@ The ``backup`` command uses the JSON lines format with the following message typ
Status
^^^^^^
+----------------------+------------------------------------------------------------+
|``message_type`` | Always "status" |
+----------------------+------------------------------------------------------------+
|``seconds_elapsed`` | Time since backup started |
+----------------------+------------------------------------------------------------+
|``seconds_remaining`` | Estimated time remaining |
+----------------------+------------------------------------------------------------+
|``percent_done`` | Percentage of data backed up (bytes_done/total_bytes) |
+----------------------+------------------------------------------------------------+
|``total_files`` | Total number of files detected |
+----------------------+------------------------------------------------------------+
|``files_done`` | Files completed (backed up to repo) |
+----------------------+------------------------------------------------------------+
|``total_bytes`` | Total number of bytes in backup set |
+----------------------+------------------------------------------------------------+
|``bytes_done`` | Number of bytes completed (backed up to repo) |
+----------------------+------------------------------------------------------------+
|``error_count`` | Number of errors |
+----------------------+------------------------------------------------------------+
|``current_files`` | List of files currently being backed up |
+----------------------+------------------------------------------------------------+
+-----------------------+-------------------------------------------------------+
| ``message_type`` | Always "status" |
+-----------------------+-------------------------------------------------------+
| ``seconds_elapsed`` | Time since backup started |
+-----------------------+-------------------------------------------------------+
| ``seconds_remaining`` | Estimated time remaining |
+-----------------------+-------------------------------------------------------+
| ``percent_done`` | Percentage of data backed up (bytes_done/total_bytes) |
+-----------------------+-------------------------------------------------------+
| ``total_files`` | Total number of files detected |
+-----------------------+-------------------------------------------------------+
| ``files_done`` | Files completed (backed up to repo) |
+-----------------------+-------------------------------------------------------+
| ``total_bytes`` | Total number of bytes in backup set |
+-----------------------+-------------------------------------------------------+
| ``bytes_done`` | Number of bytes completed (backed up to repo) |
+-----------------------+-------------------------------------------------------+
| ``error_count`` | Number of errors |
+-----------------------+-------------------------------------------------------+
| ``current_files`` | List of files currently being backed up |
+-----------------------+-------------------------------------------------------+
Error
^^^^^
These errors are printed on ``stderr``.
+----------------------+-------------------------------------------+
+-------------------+-------------------------------------------+
| ``message_type`` | Always "error" |
+----------------------+-------------------------------------------+
+-------------------+-------------------------------------------+
| ``error.message`` | Error message |
+----------------------+-------------------------------------------+
+-------------------+-------------------------------------------+
| ``during`` | What restic was trying to do |
+----------------------+-------------------------------------------+
+-------------------+-------------------------------------------+
| ``item`` | Usually, the path of the problematic file |
+----------------------+-------------------------------------------+
+-------------------+-------------------------------------------+
Verbose Status
^^^^^^^^^^^^^^
Verbose status provides details about the progress, including details about backed up files.
+----------------------+-----------------------------------------------------------+
+-------------------+----------------------------------------------------------+
| ``message_type`` | Always "verbose_status" |
+----------------------+-----------------------------------------------------------+
+-------------------+----------------------------------------------------------+
| ``action`` | Either "new", "unchanged", "modified" or "scan_finished" |
+----------------------+-----------------------------------------------------------+
+-------------------+----------------------------------------------------------+
| ``item`` | The item in question |
+----------------------+-----------------------------------------------------------+
+-------------------+----------------------------------------------------------+
| ``duration`` | How long it took, in seconds |
+----------------------+-----------------------------------------------------------+
+-------------------+----------------------------------------------------------+
| ``data_size`` | How big the item is |
+----------------------+-----------------------------------------------------------+
+-------------------+----------------------------------------------------------+
| ``metadata_size`` | How big the metadata is |
+----------------------+-----------------------------------------------------------+
+-------------------+----------------------------------------------------------+
| ``total_files`` | Total number of files |
+----------------------+-----------------------------------------------------------+
+-------------------+----------------------------------------------------------+
Summary
^^^^^^^
Summary is the last output line in a successful backup.
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``message_type`` | Always "summary" |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``files_new`` | Number of new files |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``files_changed`` | Number of files that changed |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``files_unmodified`` | Number of files that did not change |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``dirs_new`` | Number of new directories |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``dirs_changed`` | Number of directories that changed |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``dirs_unmodified`` | Number of directories that did not change |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``data_blobs`` | Number of data blobs added |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``tree_blobs`` | Number of tree blobs added |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``data_added`` | Amount of (uncompressed) data added, in bytes |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``data_added_packed`` | Amount of data added (after compression), in bytes |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``total_files_processed`` | Total number of files processed |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``total_bytes_processed`` | Total number of bytes processed |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``backup_start`` | Time at which the backup was started |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``backup_end`` | Time at which the backup was completed |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``total_duration`` | Total time it took for the operation to complete |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
| ``snapshot_id`` | ID of the new snapshot. Field is omitted if snapshot |
| | creation was skipped |
+---------------------------+---------------------------------------------------------+
+---------------------------+------------------------------------------------------+
cat
@ -270,11 +270,11 @@ Error
These errors are printed on ``stderr``.
+----------------------+---------------------------------------------------------------------+
+------------------+---------------------------------------------------------------------+
| ``message_type`` | Always "error" |
+----------------------+---------------------------------------------------------------------+
+------------------+---------------------------------------------------------------------+
| ``message`` | Error message. May change in arbitrary ways across restic versions. |
+----------------------+---------------------------------------------------------------------+
+------------------+---------------------------------------------------------------------+
diff
@ -340,13 +340,13 @@ If the ``--blob`` or ``--tree`` option is passed, then the output is an array of
Blob objects.
+-----------------+----------------------------------------------+
+--------------+------------------------------------------+
| ``hits`` | Number of matches in the snapshot |
+-----------------+----------------------------------------------+
+--------------+------------------------------------------+
| ``snapshot`` | ID of the snapshot |
+-----------------+----------------------------------------------+
+--------------+------------------------------------------+
| ``matches`` | Array of Match objects detailing a match |
+-----------------+----------------------------------------------+
+--------------+------------------------------------------+
Match object
@ -459,13 +459,13 @@ Snapshot object
Reason object
+----------------+-----------------------------------------------------------+
+--------------+-----------------------------------------------------------+
| ``snapshot`` | Snapshot object, including ``id`` and ``short_id`` fields |
+----------------+-----------------------------------------------------------+
+--------------+-----------------------------------------------------------+
| ``matches`` | Array containing descriptions of the matching criteria |
+----------------+-----------------------------------------------------------+
+--------------+-----------------------------------------------------------+
| ``counters`` | Object containing counters used by the policies |
+----------------+-----------------------------------------------------------+
+--------------+-----------------------------------------------------------+
init
@ -473,13 +473,13 @@ init
The ``init`` command uses the JSON lines format, but only outputs a single message.
+------------------+--------------------------------+
+------------------+------------------------------+
| ``message_type`` | Always "initialized" |
+------------------+--------------------------------+
+------------------+------------------------------+
| ``id`` | ID of the created repository |
+------------------+--------------------------------+
+------------------+------------------------------+
| ``repository`` | URL of the repository |
+------------------+--------------------------------+
+------------------+------------------------------+
key list
@ -487,17 +487,17 @@ key list
The ``key list`` command returns an array of objects with the following structure.
+--------------+------------------------------------+
+--------------+-----------------------------------+
| ``current`` | Is currently used key? |
+--------------+------------------------------------+
+--------------+-----------------------------------+
| ``id`` | Unique key ID |
+--------------+------------------------------------+
+--------------+-----------------------------------+
| ``userName`` | User who created it |
+--------------+------------------------------------+
+--------------+-----------------------------------+
| ``hostName`` | Name of machine it was created on |
+--------------+------------------------------------+
+--------------+-----------------------------------+
| ``created`` | Timestamp when it was created |
+--------------+------------------------------------+
+--------------+-----------------------------------+
.. _ls json:
@ -582,42 +582,42 @@ The ``restore`` command uses the JSON lines format with the following message ty
Status
^^^^^^
+----------------------+------------------------------------------------------------+
|``message_type`` | Always "status" |
+----------------------+------------------------------------------------------------+
|``seconds_elapsed`` | Time since restore started |
+----------------------+------------------------------------------------------------+
|``percent_done`` | Percentage of data restored (bytes_restored/total_bytes) |
+----------------------+------------------------------------------------------------+
|``total_files`` | Total number of files detected |
+----------------------+------------------------------------------------------------+
|``files_restored`` | Files restored |
+----------------------+------------------------------------------------------------+
|``files_skipped`` | Files skipped due to overwrite setting |
+----------------------+------------------------------------------------------------+
|``files_deleted`` | Files deleted |
+----------------------+------------------------------------------------------------+
|``total_bytes`` | Total number of bytes in restore set |
+----------------------+------------------------------------------------------------+
|``bytes_restored`` | Number of bytes restored |
+----------------------+------------------------------------------------------------+
|``bytes_skipped`` | Total size of skipped files |
+----------------------+------------------------------------------------------------+
+---------------------+----------------------------------------------------------+
| ``message_type`` | Always "status" |
+---------------------+----------------------------------------------------------+
| ``seconds_elapsed`` | Time since restore started |
+---------------------+----------------------------------------------------------+
| ``percent_done`` | Percentage of data restored (bytes_restored/total_bytes) |
+---------------------+----------------------------------------------------------+
| ``total_files`` | Total number of files detected |
+---------------------+----------------------------------------------------------+
| ``files_restored`` | Files restored |
+---------------------+----------------------------------------------------------+
| ``files_skipped`` | Files skipped due to overwrite setting |
+---------------------+----------------------------------------------------------+
| ``files_deleted`` | Files deleted |
+---------------------+----------------------------------------------------------+
| ``total_bytes`` | Total number of bytes in restore set |
+---------------------+----------------------------------------------------------+
| ``bytes_restored`` | Number of bytes restored |
+---------------------+----------------------------------------------------------+
| ``bytes_skipped`` | Total size of skipped files |
+---------------------+----------------------------------------------------------+
Error
^^^^^
These errors are printed on ``stderr``.
+----------------------+-------------------------------------------+
+-------------------+-------------------------------------------+
| ``message_type`` | Always "error" |
+----------------------+-------------------------------------------+
+-------------------+-------------------------------------------+
| ``error.message`` | Error message |
+----------------------+-------------------------------------------+
+-------------------+-------------------------------------------+
| ``during`` | Always "restore" |
+----------------------+-------------------------------------------+
+-------------------+-------------------------------------------+
| ``item`` | Usually, the path of the problematic file |
+----------------------+-------------------------------------------+
+-------------------+-------------------------------------------+
Verbose Status
^^^^^^^^^^^^^^
@ -625,38 +625,38 @@ Verbose Status
Verbose status provides details about the progress, including details about restored files.
Only printed if `--verbose=2` is specified.
+----------------------+-----------------------------------------------------------+
+------------------+--------------------------------------------------------+
| ``message_type`` | Always "verbose_status" |
+----------------------+-----------------------------------------------------------+
+------------------+--------------------------------------------------------+
| ``action`` | Either "restored", "updated", "unchanged" or "deleted" |
+----------------------+-----------------------------------------------------------+
+------------------+--------------------------------------------------------+
| ``item`` | The item in question |
+----------------------+-----------------------------------------------------------+
+------------------+--------------------------------------------------------+
| ``size`` | Size of the item in bytes |
+----------------------+-----------------------------------------------------------+
+------------------+--------------------------------------------------------+
Summary
^^^^^^^
+----------------------+------------------------------------------------------------+
|``message_type`` | Always "summary" |
+----------------------+------------------------------------------------------------+
|``seconds_elapsed`` | Time since restore started |
+----------------------+------------------------------------------------------------+
|``total_files`` | Total number of files detected |
+----------------------+------------------------------------------------------------+
|``files_restored`` | Files restored |
+----------------------+------------------------------------------------------------+
|``files_skipped`` | Files skipped due to overwrite setting |
+----------------------+------------------------------------------------------------+
|``files_deleted`` | Files deleted |
+----------------------+------------------------------------------------------------+
|``total_bytes`` | Total number of bytes in restore set |
+----------------------+------------------------------------------------------------+
|``bytes_restored`` | Number of bytes restored |
+----------------------+------------------------------------------------------------+
|``bytes_skipped`` | Total size of skipped files |
+----------------------+------------------------------------------------------------+
+---------------------+----------------------------------------+
| ``message_type`` | Always "summary" |
+---------------------+----------------------------------------+
| ``seconds_elapsed`` | Time since restore started |
+---------------------+----------------------------------------+
| ``total_files`` | Total number of files detected |
+---------------------+----------------------------------------+
| ``files_restored`` | Files restored |
+---------------------+----------------------------------------+
| ``files_skipped`` | Files skipped due to overwrite setting |
+---------------------+----------------------------------------+
| ``files_deleted`` | Files deleted |
+---------------------+----------------------------------------+
| ``total_bytes`` | Total number of bytes in restore set |
+---------------------+----------------------------------------+
| ``bytes_restored`` | Number of bytes restored |
+---------------------+----------------------------------------+
| ``bytes_skipped`` | Total size of skipped files |
+---------------------+----------------------------------------+
snapshots
@ -699,35 +699,35 @@ Summary object
The contained statistics reflect the information at the point in time when the snapshot
was created.
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``backup_start`` | Time at which the backup was started |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``backup_end`` | Time at which the backup was completed |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``files_new`` | Number of new files |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``files_changed`` | Number of files that changed |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``files_unmodified`` | Number of files that did not change |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``dirs_new`` | Number of new directories |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``dirs_changed`` | Number of directories that changed |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``dirs_unmodified`` | Number of directories that did not change |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``data_blobs`` | Number of data blobs added |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``tree_blobs`` | Number of tree blobs added |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``data_added`` | Amount of (uncompressed) data added, in bytes |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``data_added_packed`` | Amount of data added (after compression), in bytes |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``total_files_processed`` | Total number of files processed |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
| ``total_bytes_processed`` | Total number of bytes processed |
+---------------------------+---------------------------------------------------------+
+---------------------------+----------------------------------------------------+
stats
@ -762,22 +762,22 @@ The ``tag`` command uses the JSON lines format with the following message types.
Changed
^^^^^^^
+--------------------------+-------------------------------------------+
+---------------------+--------------------------------------+
| ``message_type`` | Always "changed" |
+--------------------------+-------------------------------------------+
+---------------------+--------------------------------------+
| ``old_snapshot_id`` | ID of the snapshot before the change |
+--------------------------+-------------------------------------------+
+---------------------+--------------------------------------+
| ``new_snapshot_id`` | ID of the snapshot after the change |
+--------------------------+-------------------------------------------+
+---------------------+--------------------------------------+
Summary
^^^^^^^
+-----------------------------+-------------------------------------------+
+----------------------------+-----------------------------------+
| ``message_type`` | Always "summary" |
+-----------------------------+-------------------------------------------+
+----------------------------+-----------------------------------+
| ``changed_snapshot_count`` | Total number of changed snapshots |
+-----------------------------+-------------------------------------------+
+----------------------------+-----------------------------------+
version
-------