diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index 8e0846cc3..9541accb1 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -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 | -+----------------------+-------------------------------------------+ ++------------------+-----------------------------+ +| ``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 | -+----------------------+-------------------------------------------+ ++-------------------+-------------------------------------------+ +| ``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 | -+----------------------+-----------------------------------------------------------+ ++-------------------+----------------------------------------------------------+ +| ``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 | -+---------------------------+---------------------------------------------------------+ ++---------------------------+------------------------------------------------------+ +| ``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. | -+----------------------+---------------------------------------------------------------------+ ++------------------+---------------------------------------------------------------------+ +| ``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 | -+-----------------+----------------------------------------------+ ++--------------+------------------------------------------+ +| ``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 | -+----------------+-----------------------------------------------------------+ ++--------------+-----------------------------------------------------------+ +| ``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 | -+------------------+--------------------------------+ ++------------------+------------------------------+ +| ``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 | -+--------------+------------------------------------+ ++--------------+-----------------------------------+ +| ``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 | -+----------------------+-------------------------------------------+ ++-------------------+-------------------------------------------+ +| ``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 | -+----------------------+-----------------------------------------------------------+ ++------------------+--------------------------------------------------------+ +| ``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 | -+---------------------------+---------------------------------------------------------+ ++---------------------------+----------------------------------------------------+ +| ``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 | -+--------------------------+-------------------------------------------+ ++---------------------+--------------------------------------+ +| ``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 | -+-----------------------------+-------------------------------------------+ ++----------------------------+-----------------------------------+ +| ``message_type`` | Always "summary" | ++----------------------------+-----------------------------------+ +| ``changed_snapshot_count`` | Total number of changed snapshots | ++----------------------------+-----------------------------------+ version -------