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

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