From 39299e36efe3de59db01bbc60f101adbf6efd6b7 Mon Sep 17 00:00:00 2001 From: Kyle Brennan Date: Fri, 15 May 2020 21:40:09 -0700 Subject: [PATCH 1/6] add json documentation --- doc/075_scripting.rst | 249 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index dc7f782dc..61c1949da 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -37,3 +37,252 @@ exit code if a different error is encountered (e.g.: incorrect password to ``cat config``) and it may print a different error message. If there are no errors, restic will return a zero exit code and print the repository metadata. + +Restic and json +*************** + +Restic can output json data if requested with the ``--json`` flag. +The structure of that data varies depending on the circumstance. The +json output of Most restic commands are documented here. + +.. note:: + Not all commands support json output. If a command does not support json output, + at the time of writing, it is not supported yet. (feel free to submit a pull request!) + +Backup +------ + +backup has multiple json structures, outlined below. + +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 or skipped) | ++----------------------+---------------------------------------------------------+ +|``total_bytes`` | Total number of bytes in backup set | ++----------------------+---------------------------------------------------------+ +|``bytes_done`` | Number of bytes completed | ++----------------------+---------------------------------------------------------+ +|``error_count`` | Number of errors | ++----------------------+---------------------------------------------------------+ +|``current_files`` | List of files currently being backed up | ++----------------------+---------------------------------------------------------+ + +Error +^^^^^ + ++----------------------+--------------------------------+ +| ``message_type`` | always "error" | ++----------------------+--------------------------------+ +| ``error`` | error message | ++----------------------+--------------------------------+ +| ``during`` | what restic was trying to do | ++----------------------+--------------------------------+ +| ``item`` | what item was being processed | ++----------------------+--------------------------------+ + +Verbose Status +^^^^^^^^^^^^^^ + ++----------------------+-------------------------------------------+ +| ``message_type`` | Always "verbose_status" | ++----------------------+-------------------------------------------+ +| ``action`` | Either "new", "unchanged" or "modified" | ++----------------------+-------------------------------------------+ +| ``item`` | The item in question | ++----------------------+-------------------------------------------+ +| ``duration`` | How long it took, in seconds | ++----------------------+-------------------------------------------+ +| ``data_size`` | How big item is | ++----------------------+-------------------------------------------+ +| ``metadata_size`` | How big the metadata is | ++----------------------+-------------------------------------------+ +| ``total_files`` | how many total files there are. | ++----------------------+-------------------------------------------+ + +Summary +^^^^^^^ + ++---------------------------+---------------------------------------------------------+ +| ``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 | ++---------------------------+---------------------------------------------------------+ +| ``tree_blobs`` | Number of tree blobs | ++---------------------------+---------------------------------------------------------+ +| ``data_added`` | Amount of data added, in bytes | ++---------------------------+---------------------------------------------------------+ +| ``total_files_processed`` | Total number of files processed | ++---------------------------+---------------------------------------------------------+ +| ``total_bytes_processed`` | Total number of bytes processed | ++---------------------------+---------------------------------------------------------+ +| ``total_duration`` | Total time it took for the operation to complete | ++---------------------------+---------------------------------------------------------+ +| ``snapshot_id`` | the ID of the new snapshot | ++---------------------------+---------------------------------------------------------+ + +snapshots +--------- + +Snapshots returns a single json structure with a number of optional fields. + ++----------------+------------------------------------------------------------------------+ +| ``hostname`` | contains the hostname of the machine that's being backed up. | ++----------------+------------------------------------------------------------------------+ +| ``username`` | contains the username that the backup command was run as. | ++----------------+------------------------------------------------------------------------+ +| ``excludes`` | contains a list of paths and globs that were excluded from the backup. | ++----------------+------------------------------------------------------------------------+ +| ``tags`` | contains a list of tags for the snapshot in question. | ++----------------+------------------------------------------------------------------------+ +| ``id`` | contains the long snapshot id. | ++----------------+------------------------------------------------------------------------+ +| ``short_id`` | contains the short snapshot id. | ++----------------+------------------------------------------------------------------------+ +| ``time`` | contains the timestamp of the backup. | ++----------------+------------------------------------------------------------------------+ +| ``parent`` | contains the id of the previous backup. | ++----------------+------------------------------------------------------------------------+ +| ``tree`` | contains something... | ++----------------+------------------------------------------------------------------------+ +| ``paths`` | contains a list of paths that were included in the backup. | ++----------------+------------------------------------------------------------------------+ + +cat +--- + +Cat will return data about various objects in the repository, already in json form. +By specifying ``--json``, it will suppress any non-json messages the command generates. + +find +---- + + ++-----------------+------------------------------------------+ +| ``path`` | Object path | ++-----------------+------------------------------------------+ +| ``permissions`` | unix permissions | ++-----------------+------------------------------------------+ +| ``type`` | what type it is e.g. file, dir, etc... | ++-----------------+------------------------------------------+ +| ``atime`` | Access time | ++-----------------+------------------------------------------+ +| ``mtime`` | Modification time | ++-----------------+------------------------------------------+ +| ``ctime`` | Creation time | ++-----------------+------------------------------------------+ +| ``name`` | Object name | ++-----------------+------------------------------------------+ +| ``user`` | Name of owner | ++-----------------+------------------------------------------+ +| ``group`` | Name of group | ++-----------------+------------------------------------------+ +| ``uid`` | ID of owner | ++-----------------+------------------------------------------+ +| ``gid`` | ID of group | ++-----------------+------------------------------------------+ +| ``size`` | size of object in bytes | ++-----------------+------------------------------------------+ + +key list +-------- + ++--------------+------------------------------------+ +| ``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 +-- + +snapshot +^^^^^^^^ + ++-----------------+-------------------------------------+ +| ``time`` | Snapshot time | ++-----------------+-------------------------------------+ +| ``tree`` | Snapshot tree root | ++-----------------+-------------------------------------+ +| ``paths`` | List of paths included in snapshot | ++-----------------+-------------------------------------+ +| ``hostname`` | hostname of snapshot | ++-----------------+-------------------------------------+ +| ``username`` | user snapshot was run as | ++-----------------+-------------------------------------+ +| ``uid`` | uid of backup process | ++-----------------+-------------------------------------+ +| ``gid`` | gid of backup process | ++-----------------+-------------------------------------+ +| ``id`` | snapshot id, long form | ++-----------------+-------------------------------------+ +| ``short_id`` | snapshot id, short form | ++-----------------+-------------------------------------+ +| ``struct_type`` | always "snapshot" | ++-----------------+-------------------------------------+ + + +node +^^^^ + ++-----------------+--------------------------+ +| ``name`` | node name | ++-----------------+--------------------------+ +| ``type`` | node type | ++-----------------+--------------------------+ +| ``path`` | node path | ++-----------------+--------------------------+ +| ``uid`` | uid of node | ++-----------------+--------------------------+ +| ``gid`` | gid of node | ++-----------------+--------------------------+ +| ``size`` | size in bytes | ++-----------------+--------------------------+ +| ``mode`` | node mode | ++-----------------+--------------------------+ +| ``atime`` | node access time | ++-----------------+--------------------------+ +| ``mtime`` | node modification time | ++-----------------+--------------------------+ +| ``ctime`` | node creation time | ++-----------------+--------------------------+ +| ``struct_type`` | always "node" | ++-----------------+--------------------------+ + +stats +----- + ++----------------------+---------------------------------------------+ +| ``total_size`` | Repository size in bytes | ++----------------------+---------------------------------------------+ +| ``total_file_count`` | Number of files backed up in the repository | ++----------------------+---------------------------------------------+ From e457fe22bc68224600d41efe1e28843b37289b5d Mon Sep 17 00:00:00 2001 From: Kyle Brennan Date: Wed, 25 Nov 2020 23:54:53 -0800 Subject: [PATCH 2/6] Documentation improvement --- doc/075_scripting.rst | 221 ++++++++++++++++++++++++------------------ 1 file changed, 127 insertions(+), 94 deletions(-) diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index 61c1949da..ec36afe43 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -38,63 +38,68 @@ to ``cat config``) and it may print a different error message. If there are no errors, restic will return a zero exit code and print the repository metadata. -Restic and json +Restic and JSON *************** Restic can output json data if requested with the ``--json`` flag. The structure of that data varies depending on the circumstance. The -json output of Most restic commands are documented here. +json output of most restic commands are documented here. .. note:: Not all commands support json output. If a command does not support json output, - at the time of writing, it is not supported yet. (feel free to submit a pull request!) + feel free to submit a pull request! Backup ------ -backup has multiple json structures, outlined below. +The backup command has multiple json structures, outlined below. + +During the backup process, Restic will print out a stream of new-line separated JSON +messages. You can determine the nature of the message by the ``message_type`` field. 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 or skipped) | -+----------------------+---------------------------------------------------------+ -|``total_bytes`` | Total number of bytes in backup set | -+----------------------+---------------------------------------------------------+ -|``bytes_done`` | Number of bytes completed | -+----------------------+---------------------------------------------------------+ -|``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 or confirmed in repo) | ++----------------------+------------------------------------------------------------+ +|``total_bytes`` | Total number of bytes in backup set | ++----------------------+------------------------------------------------------------+ +|``bytes_done`` | Number of bytes completed (backed up or confirmed in repo) | ++----------------------+------------------------------------------------------------+ +|``error_count`` | Number of errors | ++----------------------+------------------------------------------------------------+ +|``current_files`` | List of files currently being backed up | ++----------------------+------------------------------------------------------------+ Error ^^^^^ -+----------------------+--------------------------------+ -| ``message_type`` | always "error" | -+----------------------+--------------------------------+ -| ``error`` | error message | -+----------------------+--------------------------------+ -| ``during`` | what restic was trying to do | -+----------------------+--------------------------------+ -| ``item`` | what item was being processed | -+----------------------+--------------------------------+ ++----------------------+-------------------------------------------+ +| ``message_type`` | Always "error" | ++----------------------+-------------------------------------------+ +| ``error`` | Error message | ++----------------------+-------------------------------------------+ +| ``during`` | What restic was trying to do | ++----------------------+-------------------------------------------+ +| ``item`` | Usually, the path of the problematic file | ++----------------------+-------------------------------------------+ Verbose Status ^^^^^^^^^^^^^^ +Verbose status is a status line that supplements + +----------------------+-------------------------------------------+ | ``message_type`` | Always "verbose_status" | +----------------------+-------------------------------------------+ @@ -104,16 +109,18 @@ Verbose Status +----------------------+-------------------------------------------+ | ``duration`` | How long it took, in seconds | +----------------------+-------------------------------------------+ -| ``data_size`` | How big item is | +| ``data_size`` | How big the item is | +----------------------+-------------------------------------------+ | ``metadata_size`` | How big the metadata is | +----------------------+-------------------------------------------+ -| ``total_files`` | how many total files there are. | +| ``total_files`` | Total number of files | +----------------------+-------------------------------------------+ Summary ^^^^^^^ +Summary is the last output line in a successful backup. + +---------------------------+---------------------------------------------------------+ | ``message_type`` | Always "summary" | +---------------------------+---------------------------------------------------------+ @@ -141,34 +148,34 @@ Summary +---------------------------+---------------------------------------------------------+ | ``total_duration`` | Total time it took for the operation to complete | +---------------------------+---------------------------------------------------------+ -| ``snapshot_id`` | the ID of the new snapshot | +| ``snapshot_id`` | The short ID of the new snapshot | +---------------------------+---------------------------------------------------------+ snapshots --------- -Snapshots returns a single json structure with a number of optional fields. +The snapshots command returns a single JSON object, an array with the structure outlined below. +----------------+------------------------------------------------------------------------+ -| ``hostname`` | contains the hostname of the machine that's being backed up. | +| ``hostname`` | The hostname of the machine that's being backed up | +----------------+------------------------------------------------------------------------+ -| ``username`` | contains the username that the backup command was run as. | +| ``username`` | The username that the backup command was run as | +----------------+------------------------------------------------------------------------+ -| ``excludes`` | contains a list of paths and globs that were excluded from the backup. | +| ``excludes`` | A list of paths and globs that were excluded from the backup | +----------------+------------------------------------------------------------------------+ -| ``tags`` | contains a list of tags for the snapshot in question. | +| ``tags`` | A list of tags for the snapshot in question | +----------------+------------------------------------------------------------------------+ -| ``id`` | contains the long snapshot id. | +| ``id`` | The long snapshot ID | +----------------+------------------------------------------------------------------------+ -| ``short_id`` | contains the short snapshot id. | +| ``short_id`` | The short snapshot ID | +----------------+------------------------------------------------------------------------+ -| ``time`` | contains the timestamp of the backup. | +| ``time`` | The timestamp of when the backup was started | +----------------+------------------------------------------------------------------------+ -| ``parent`` | contains the id of the previous backup. | +| ``parent`` | The ID of the previous snapshot | +----------------+------------------------------------------------------------------------+ -| ``tree`` | contains something... | +| ``tree`` | The ID of the root tree blob | +----------------+------------------------------------------------------------------------+ -| ``paths`` | contains a list of paths that were included in the backup. | +| ``paths`` | A list of paths that were included in the backup | +----------------+------------------------------------------------------------------------+ cat @@ -180,51 +187,75 @@ By specifying ``--json``, it will suppress any non-json messages the command gen find ---- +The find command outputs an array of json objects with matches for your search term. These +matches are organized by snapshot. -+-----------------+------------------------------------------+ -| ``path`` | Object path | -+-----------------+------------------------------------------+ -| ``permissions`` | unix permissions | -+-----------------+------------------------------------------+ -| ``type`` | what type it is e.g. file, dir, etc... | -+-----------------+------------------------------------------+ -| ``atime`` | Access time | -+-----------------+------------------------------------------+ -| ``mtime`` | Modification time | -+-----------------+------------------------------------------+ -| ``ctime`` | Creation time | -+-----------------+------------------------------------------+ -| ``name`` | Object name | -+-----------------+------------------------------------------+ -| ``user`` | Name of owner | -+-----------------+------------------------------------------+ -| ``group`` | Name of group | -+-----------------+------------------------------------------+ -| ``uid`` | ID of owner | -+-----------------+------------------------------------------+ -| ``gid`` | ID of group | -+-----------------+------------------------------------------+ -| ``size`` | size of object in bytes | -+-----------------+------------------------------------------+ +Snapshot +^^^^^^^^ + ++-----------------+----------------------------------------------+ +| ``hits`` | The number of matches in the snapshot | ++-----------------+----------------------------------------------+ +| ``snapshot`` | The long ID of the snapshot | ++-----------------+----------------------------------------------+ +| ``matches`` | Array of JSON objects detailing a match. | ++-----------------+----------------------------------------------+ + + +Match +^^^^^ + ++-----------------+----------------------------------------------+ +| ``path`` | Object path | ++-----------------+----------------------------------------------+ +| ``permissions`` | UNIX permissions | ++-----------------+----------------------------------------------+ +| ``type`` | what type it is e.g. file, dir, etc... | ++-----------------+----------------------------------------------+ +| ``atime`` | Access time | ++-----------------+----------------------------------------------+ +| ``mtime`` | Modification time | ++-----------------+----------------------------------------------+ +| ``ctime`` | Change time | ++-----------------+----------------------------------------------+ +| ``name`` | Object name | ++-----------------+----------------------------------------------+ +| ``user`` | Name of owner | ++-----------------+----------------------------------------------+ +| ``group`` | Name of group | ++-----------------+----------------------------------------------+ +| ``mode`` | UNIX file mode, shorthand of ``permissions`` | ++-----------------+----------------------------------------------+ +| ``uid`` | ID of owner | ++-----------------+----------------------------------------------+ +| ``gid`` | ID of group | ++-----------------+----------------------------------------------+ +| ``size`` | Size of object in bytes | ++-----------------+----------------------------------------------+ 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 | +| ``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 -- +The ls command spits out a series of newline-separated JSON objects, +the nature of which can be determined by the ``struct_type`` field. + snapshot ^^^^^^^^ @@ -235,19 +266,19 @@ snapshot +-----------------+-------------------------------------+ | ``paths`` | List of paths included in snapshot | +-----------------+-------------------------------------+ -| ``hostname`` | hostname of snapshot | +| ``hostname`` | Hostname of snapshot | +-----------------+-------------------------------------+ -| ``username`` | user snapshot was run as | +| ``username`` | User snapshot was run as | +-----------------+-------------------------------------+ -| ``uid`` | uid of backup process | +| ``uid`` | UID of backup process | +-----------------+-------------------------------------+ -| ``gid`` | gid of backup process | +| ``gid`` | GID of backup process | +-----------------+-------------------------------------+ -| ``id`` | snapshot id, long form | +| ``id`` | Snapshot ID, long form | +-----------------+-------------------------------------+ -| ``short_id`` | snapshot id, short form | +| ``short_id`` | Snapshot ID, short form | +-----------------+-------------------------------------+ -| ``struct_type`` | always "snapshot" | +| ``struct_type`` | Always "snapshot" | +-----------------+-------------------------------------+ @@ -255,27 +286,27 @@ node ^^^^ +-----------------+--------------------------+ -| ``name`` | node name | +| ``name`` | Node name | +-----------------+--------------------------+ -| ``type`` | node type | +| ``type`` | Node type | +-----------------+--------------------------+ -| ``path`` | node path | +| ``path`` | Node path | +-----------------+--------------------------+ -| ``uid`` | uid of node | +| ``uid`` | UID of node | +-----------------+--------------------------+ -| ``gid`` | gid of node | +| ``gid`` | GID of node | +-----------------+--------------------------+ -| ``size`` | size in bytes | +| ``size`` | Size in bytes | +-----------------+--------------------------+ -| ``mode`` | node mode | +| ``mode`` | Node mode | +-----------------+--------------------------+ -| ``atime`` | node access time | +| ``atime`` | Node access time | +-----------------+--------------------------+ -| ``mtime`` | node modification time | +| ``mtime`` | Node modification time | +-----------------+--------------------------+ -| ``ctime`` | node creation time | +| ``ctime`` | Node creation time | +-----------------+--------------------------+ -| ``struct_type`` | always "node" | +| ``struct_type`` | Always "node" | +-----------------+--------------------------+ stats @@ -286,3 +317,5 @@ stats +----------------------+---------------------------------------------+ | ``total_file_count`` | Number of files backed up in the repository | +----------------------+---------------------------------------------+ +| ``total_blob_count`` | Number of blobs in the repository | ++----------------------+---------------------------------------------+ From fb1170c1d6c996d36d5176d27fa3c3198ad5c4bb Mon Sep 17 00:00:00 2001 From: Kyle Brennan Date: Thu, 26 Nov 2020 00:21:08 -0800 Subject: [PATCH 3/6] doc tweaks --- doc/075_scripting.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index ec36afe43..0fada390d 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -226,6 +226,10 @@ Match +-----------------+----------------------------------------------+ | ``mode`` | UNIX file mode, shorthand of ``permissions`` | +-----------------+----------------------------------------------+ +| ``device_id`` | Unique machine Identifier | ++-----------------+----------------------------------------------+ +| ``links`` | Number of hardlinks | ++-----------------+----------------------------------------------+ | ``uid`` | ID of owner | +-----------------+----------------------------------------------+ | ``gid`` | ID of group | @@ -270,9 +274,9 @@ snapshot +-----------------+-------------------------------------+ | ``username`` | User snapshot was run as | +-----------------+-------------------------------------+ -| ``uid`` | UID of backup process | +| ``uid`` | ID of owner | +-----------------+-------------------------------------+ -| ``gid`` | GID of backup process | +| ``gid`` | ID of group | +-----------------+-------------------------------------+ | ``id`` | Snapshot ID, long form | +-----------------+-------------------------------------+ From 1ce839228e39aa29f95e28fcc371b9f72f193311 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Fri, 9 Jun 2023 00:46:55 +0200 Subject: [PATCH 4/6] doc: Expand JSON documentation --- doc/075_scripting.rst | 414 +++++++++++++++++++++++++++++++----------- 1 file changed, 308 insertions(+), 106 deletions(-) diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index 0fada390d..9855b9ffb 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -38,24 +38,50 @@ to ``cat config``) and it may print a different error message. If there are no errors, restic will return a zero exit code and print the repository metadata. -Restic and JSON -*************** +JSON output +*********** -Restic can output json data if requested with the ``--json`` flag. +Restic outputs JSON data to ``stdout`` if requested with the ``--json`` flag. The structure of that data varies depending on the circumstance. The -json output of most restic commands are documented here. +JSON output of most restic commands are documented here. .. note:: - Not all commands support json output. If a command does not support json output, + Not all commands support JSON output. If a command does not support JSON output, feel free to submit a pull request! -Backup +.. warning:: + We try to keep the JSON output backwards compatible. However, new message types + or fields may be added at any time. Similarly, enum-like fields for which a fixed + list of allowed values is documented may be extended at any time. + + +Output formats +-------------- + +Currently only the output on ``stdout`` is JSON formatted. Errors printed on ``stderr`` +are still printed as plain text messages. The generated JSON output uses one of the +following two formats. + +Single JSON document +^^^^^^^^^^^^^^^^^^^^ + +Several commands output a single JSON document that can be parsed in its entirety. +Depending on the command, the output consists of either a single or multiple lines. + +JSON lines +^^^^^^^^^^ + +Several commands, in particular long running ones or those that generate a large output, +use a format also known as JSON lines. It consists of a stream of new-line separated JSON +messages. You can determine the nature of the message using the ``message_type`` field. + +As an exception, the ``ls`` command uses the field ``struct_type`` instead. + + +backup ------ -The backup command has multiple json structures, outlined below. - -During the backup process, Restic will print out a stream of new-line separated JSON -messages. You can determine the nature of the message by the ``message_type`` field. +The ``backup`` command uses the JSON lines format with the following message types. Status ^^^^^^ @@ -71,11 +97,11 @@ Status +----------------------+------------------------------------------------------------+ |``total_files`` | Total number of files detected | +----------------------+------------------------------------------------------------+ -|``files_done`` | Files completed (backed up or confirmed in repo) | +|``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 or confirmed in repo) | +|``bytes_done`` | Number of bytes completed (backed up to repo) | +----------------------+------------------------------------------------------------+ |``error_count`` | Number of errors | +----------------------+------------------------------------------------------------+ @@ -98,23 +124,23 @@ Error Verbose Status ^^^^^^^^^^^^^^ -Verbose status is a status line that supplements +Verbose status provides details about the progress, including details about backed up files. -+----------------------+-------------------------------------------+ -| ``message_type`` | Always "verbose_status" | -+----------------------+-------------------------------------------+ -| ``action`` | Either "new", "unchanged" or "modified" | -+----------------------+-------------------------------------------+ -| ``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 ^^^^^^^ @@ -148,69 +174,96 @@ Summary is the last output line in a successful backup. +---------------------------+---------------------------------------------------------+ | ``total_duration`` | Total time it took for the operation to complete | +---------------------------+---------------------------------------------------------+ -| ``snapshot_id`` | The short ID of the new snapshot | +| ``snapshot_id`` | ID of the new snapshot | +---------------------------+---------------------------------------------------------+ -snapshots ---------- - -The snapshots command returns a single JSON object, an array with the structure outlined below. - -+----------------+------------------------------------------------------------------------+ -| ``hostname`` | The hostname of the machine that's being backed up | -+----------------+------------------------------------------------------------------------+ -| ``username`` | The username that the backup command was run as | -+----------------+------------------------------------------------------------------------+ -| ``excludes`` | A list of paths and globs that were excluded from the backup | -+----------------+------------------------------------------------------------------------+ -| ``tags`` | A list of tags for the snapshot in question | -+----------------+------------------------------------------------------------------------+ -| ``id`` | The long snapshot ID | -+----------------+------------------------------------------------------------------------+ -| ``short_id`` | The short snapshot ID | -+----------------+------------------------------------------------------------------------+ -| ``time`` | The timestamp of when the backup was started | -+----------------+------------------------------------------------------------------------+ -| ``parent`` | The ID of the previous snapshot | -+----------------+------------------------------------------------------------------------+ -| ``tree`` | The ID of the root tree blob | -+----------------+------------------------------------------------------------------------+ -| ``paths`` | A list of paths that were included in the backup | -+----------------+------------------------------------------------------------------------+ cat --- -Cat will return data about various objects in the repository, already in json form. -By specifying ``--json``, it will suppress any non-json messages the command generates. +The ``cat`` command returns data about various objects in the repository, which +are stored in JSON form. Specifying ``--json`` or ``--quiet`` will suppress any +non-JSON messages the command generates. + + +diff +---- + +The ``diff`` command uses the JSON lines format with the following message types. + +change +^^^^^^ + ++------------------+--------------------------------------------------------------+ +| ``message_type`` | Always "change" | ++------------------+--------------------------------------------------------------+ +| ``path`` | Path that has changed | ++------------------+--------------------------------------------------------------+ +| ``modifier`` | Type of change, a concatenation of the following characters: | +| | "+" = added, "-" = removed, "T" = entry type changed, | +| | "M" = file content changed, "U" = metadata changed | ++------------------+--------------------------------------------------------------+ + +statistics +^^^^^^^^^^ + ++---------------------+----------------------------+ +| ``message_type`` | Always "statistics" | ++---------------------+----------------------------+ +| ``source_snapshot`` | ID of first snapshot | ++---------------------+----------------------------+ +| ``target_snapshot`` | ID of second snapshot | ++---------------------+----------------------------+ +| ``changed_files`` | Number of changed files | ++---------------------+----------------------------+ +| ``added`` | DiffStat object, see below | ++---------------------+----------------------------+ +| ``removed`` | DiffStat object, see below | ++---------------------+----------------------------+ + +DiffStat object + ++----------------+-------------------------------------------+ +| ``files`` | Number of changed files | ++----------------+-------------------------------------------+ +| ``dirs`` | Number of changed directories | ++----------------+-------------------------------------------+ +| ``others`` | Number of changed other directory entries | ++----------------+-------------------------------------------+ +| ``data_blobs`` | Number of data blobs | ++----------------+-------------------------------------------+ +| ``tree_blobs`` | Number of tree blobs | ++----------------+-------------------------------------------+ +| ``bytes`` | Number of bytes | ++----------------+-------------------------------------------+ + find ---- -The find command outputs an array of json objects with matches for your search term. These -matches are organized by snapshot. +The ``find`` command outputs a single JSON document containing an array of JSON +objects with matches for your search term. These matches are organized by snapshot. -Snapshot -^^^^^^^^ - -+-----------------+----------------------------------------------+ -| ``hits`` | The number of matches in the snapshot | -+-----------------+----------------------------------------------+ -| ``snapshot`` | The long ID of the snapshot | -+-----------------+----------------------------------------------+ -| ``matches`` | Array of JSON objects detailing a match. | -+-----------------+----------------------------------------------+ +If the ``--blob`` or ``--tree`` option is passed, then the output is an array of +Blob objects. -Match -^^^^^ ++-----------------+----------------------------------------------+ +| ``hits`` | Number of matches in the snapshot | ++-----------------+----------------------------------------------+ +| ``snapshot`` | ID of the snapshot | ++-----------------+----------------------------------------------+ +| ``matches`` | Array of Match objects detailing a match | ++-----------------+----------------------------------------------+ + +Match object +-----------------+----------------------------------------------+ | ``path`` | Object path | +-----------------+----------------------------------------------+ | ``permissions`` | UNIX permissions | +-----------------+----------------------------------------------+ -| ``type`` | what type it is e.g. file, dir, etc... | +| ``type`` | Object type e.g. file, dir, etc... | +-----------------+----------------------------------------------+ | ``atime`` | Access time | +-----------------+----------------------------------------------+ @@ -226,7 +279,7 @@ Match +-----------------+----------------------------------------------+ | ``mode`` | UNIX file mode, shorthand of ``permissions`` | +-----------------+----------------------------------------------+ -| ``device_id`` | Unique machine Identifier | +| ``device_id`` | OS specific device identifier | +-----------------+----------------------------------------------+ | ``links`` | Number of hardlinks | +-----------------+----------------------------------------------+ @@ -237,10 +290,106 @@ Match | ``size`` | Size of object in bytes | +-----------------+----------------------------------------------+ +Blob object + ++-----------------+--------------------------------------------+ +| ``object_type`` | Either "blob" or "tree" | ++-----------------+--------------------------------------------+ +| ``id`` | ID of found blob | ++-----------------+--------------------------------------------+ +| ``path`` | Path in snapshot | ++-----------------+--------------------------------------------+ +| ``parent_tree`` | Parent tree blob, only set for type "blob" | ++-----------------+--------------------------------------------+ +| ``snapshot`` | Snapshot ID | ++-----------------+--------------------------------------------+ +| ``time`` | Snapshot timestamp | ++-----------------+--------------------------------------------+ + + +forget +------ + +The ``forget`` command prints a single JSON document containing an array of +ForgetGroups. If specific snapshot IDs are specified, then no output is generated. + +The ``prune`` command does not yet support JSON such that ``forget --prune`` +results in a mix of JSON and text output. + +ForgetGroup +^^^^^^^^^^^ + ++-------------+-----------------------------------------------------------+ +| ``tags`` | Tags identifying the snapshot group | ++-------------+-----------------------------------------------------------+ +| ``host`` | Host identifying the snapshot group | ++-------------+-----------------------------------------------------------+ +| ``paths`` | Paths identifying the snapshot group | ++-------------+-----------------------------------------------------------+ +| ``keep`` | Array of Snapshot objects that are kept | ++-------------+-----------------------------------------------------------+ +| ``remove`` | Array of Snapshot objects that were removed | ++-------------+-----------------------------------------------------------+ +| ``reasons`` | Array of Reason objects describing why a snapshot is kept | ++-------------+-----------------------------------------------------------+ + +Snapshot object + ++----------------+--------------------------------------------------+ +| ``time`` | Timestamp of when the backup was started | ++----------------+--------------------------------------------------+ +| ``parent`` | ID of the parent snapshot | ++----------------+--------------------------------------------------+ +| ``tree`` | ID of the root tree blob | ++----------------+--------------------------------------------------+ +| ``paths`` | List of paths included in the backup | ++----------------+--------------------------------------------------+ +| ``hostname`` | Hostname of the backed up machine | ++----------------+--------------------------------------------------+ +| ``username`` | Username the backup command was run as | ++----------------+--------------------------------------------------+ +| ``uid`` | ID of owner | ++----------------+--------------------------------------------------+ +| ``gid`` | ID of group | ++----------------+--------------------------------------------------+ +| ``excludes`` | List of paths and globs excluded from the backup | ++----------------+--------------------------------------------------+ +| ``tags`` | List of tags for the snapshot in question | ++----------------+--------------------------------------------------+ +| ``id`` | Snapshot ID | ++----------------+--------------------------------------------------+ +| ``short_id`` | Snapshot ID, short form | ++----------------+--------------------------------------------------+ + +Reason object + ++----------------+---------------------------------------------------------+ +| ``snapshot`` | Snapshot object, without ``id`` and ``short_id`` fields | ++----------------+---------------------------------------------------------+ +| ``matches`` | Array containing descriptions of the matching criteria | ++----------------+---------------------------------------------------------+ +| ``counters`` | Object containing counters used by the policies | ++----------------+---------------------------------------------------------+ + + +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 -------- -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? | @@ -254,41 +403,50 @@ The key list command returns an array of objects with the following structure. | ``created`` | Timestamp when it was created | +--------------+------------------------------------+ + ls -- -The ls command spits out a series of newline-separated JSON objects, -the nature of which can be determined by the ``struct_type`` field. +The ``ls`` command uses the JSON lines format with the following message types. +As an exception, the ``struct_type`` field is used to determine the message type. snapshot ^^^^^^^^ -+-----------------+-------------------------------------+ -| ``time`` | Snapshot time | -+-----------------+-------------------------------------+ -| ``tree`` | Snapshot tree root | -+-----------------+-------------------------------------+ -| ``paths`` | List of paths included in snapshot | -+-----------------+-------------------------------------+ -| ``hostname`` | Hostname of snapshot | -+-----------------+-------------------------------------+ -| ``username`` | User snapshot was run as | -+-----------------+-------------------------------------+ -| ``uid`` | ID of owner | -+-----------------+-------------------------------------+ -| ``gid`` | ID of group | -+-----------------+-------------------------------------+ -| ``id`` | Snapshot ID, long form | -+-----------------+-------------------------------------+ -| ``short_id`` | Snapshot ID, short form | -+-----------------+-------------------------------------+ -| ``struct_type`` | Always "snapshot" | -+-----------------+-------------------------------------+ ++----------------+--------------------------------------------------+ +| ``struct_type``| Always "snapshot" | ++----------------+--------------------------------------------------+ +| ``time`` | Timestamp of when the backup was started | ++----------------+--------------------------------------------------+ +| ``parent`` | ID of the parent snapshot | ++----------------+--------------------------------------------------+ +| ``tree`` | ID of the root tree blob | ++----------------+--------------------------------------------------+ +| ``paths`` | List of paths included in the backup | ++----------------+--------------------------------------------------+ +| ``hostname`` | Hostname of the backed up machine | ++----------------+--------------------------------------------------+ +| ``username`` | Username the backup command was run as | ++----------------+--------------------------------------------------+ +| ``uid`` | ID of owner | ++----------------+--------------------------------------------------+ +| ``gid`` | ID of group | ++----------------+--------------------------------------------------+ +| ``excludes`` | List of paths and globs excluded from the backup | ++----------------+--------------------------------------------------+ +| ``tags`` | List of tags for the snapshot in question | ++----------------+--------------------------------------------------+ +| ``id`` | Snapshot ID | ++----------------+--------------------------------------------------+ +| ``short_id`` | Snapshot ID, short form | ++----------------+--------------------------------------------------+ node ^^^^ ++-----------------+--------------------------+ +| ``struct_type`` | Always "node" | +-----------------+--------------------------+ | ``name`` | Node name | +-----------------+--------------------------+ @@ -310,16 +468,60 @@ node +-----------------+--------------------------+ | ``ctime`` | Node creation time | +-----------------+--------------------------+ -| ``struct_type`` | Always "node" | -+-----------------+--------------------------+ + + +snapshots +--------- + +The snapshots command returns a single JSON object, an array with objects of the structure outlined below. + ++----------------+--------------------------------------------------+ +| ``time`` | Timestamp of when the backup was started | ++----------------+--------------------------------------------------+ +| ``parent`` | ID of the parent snapshot | ++----------------+--------------------------------------------------+ +| ``tree`` | ID of the root tree blob | ++----------------+--------------------------------------------------+ +| ``paths`` | List of paths included in the backup | ++----------------+--------------------------------------------------+ +| ``hostname`` | Hostname of the backed up machine | ++----------------+--------------------------------------------------+ +| ``username`` | Username the backup command was run as | ++----------------+--------------------------------------------------+ +| ``uid`` | ID of owner | ++----------------+--------------------------------------------------+ +| ``gid`` | ID of group | ++----------------+--------------------------------------------------+ +| ``excludes`` | List of paths and globs excluded from the backup | ++----------------+--------------------------------------------------+ +| ``tags`` | List of tags for the snapshot in question | ++----------------+--------------------------------------------------+ +| ``id`` | Snapshot ID | ++----------------+--------------------------------------------------+ +| ``short_id`` | Snapshot ID, short form | ++----------------+--------------------------------------------------+ + stats ----- -+----------------------+---------------------------------------------+ -| ``total_size`` | Repository size in bytes | -+----------------------+---------------------------------------------+ -| ``total_file_count`` | Number of files backed up in the repository | -+----------------------+---------------------------------------------+ -| ``total_blob_count`` | Number of blobs in the repository | -+----------------------+---------------------------------------------+ +The snapshots command returns a single JSON object. + ++------------------------------+-----------------------------------------------------+ +| ``total_size`` | Repository size in bytes | ++------------------------------+-----------------------------------------------------+ +| ``total_file_count`` | Number of files backed up in the repository | ++------------------------------+-----------------------------------------------------+ +| ``total_blob_count`` | Number of blobs in the repository | ++------------------------------+-----------------------------------------------------+ +| ``snapshots_count`` | Number of processed snapshots | ++------------------------------+-----------------------------------------------------+ +| ``total_uncompressed_size`` | Repository size in bytes if blobs were uncompressed | ++------------------------------+-----------------------------------------------------+ +| ``compression_ratio`` | Factor by which the already compressed data | +| | has shrunk due to compression | ++------------------------------+-----------------------------------------------------+ +| ``compression_progress`` | Percentage of already compressed data | ++------------------------------+-----------------------------------------------------+ +| ``compression_space_saving`` | Overall space saving due to compression | ++------------------------------+-----------------------------------------------------+ From b34ce57dd4d48059d183d92afc6d14c0e7a276b6 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Sat, 17 Jun 2023 21:47:17 +0200 Subject: [PATCH 5/6] doc: describe JSON output of restore command --- doc/075_scripting.rst | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index 9855b9ffb..85c67ab38 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -470,6 +470,49 @@ node +-----------------+--------------------------+ +restore +------- + +The ``restore`` command uses the JSON lines format with the following message types. + +Status +^^^^^^ + ++----------------------+------------------------------------------------------------+ +|``message_type`` | Always "status" | ++----------------------+------------------------------------------------------------+ +|``seconds_elapsed`` | Time since restore started | ++----------------------+------------------------------------------------------------+ +|``percent_done`` | Percentage of data backed up (bytes_restored/total_bytes) | ++----------------------+------------------------------------------------------------+ +|``total_files`` | Total number of files detected | ++----------------------+------------------------------------------------------------+ +|``files_restored`` | Files restored | ++----------------------+------------------------------------------------------------+ +|``total_bytes`` | Total number of bytes in restore set | ++----------------------+------------------------------------------------------------+ +|``bytes_restored`` | Number of bytes restored | ++----------------------+------------------------------------------------------------+ + + +Summary +^^^^^^^ + ++----------------------+------------------------------------------------------------+ +|``message_type`` | Always "summary" | ++----------------------+------------------------------------------------------------+ +|``seconds_elapsed`` | Time since restore started | ++----------------------+------------------------------------------------------------+ +|``total_files`` | Total number of files detected | ++----------------------+------------------------------------------------------------+ +|``files_restored`` | Files restored | ++----------------------+------------------------------------------------------------+ +|``total_bytes`` | Total number of bytes in restore set | ++----------------------+------------------------------------------------------------+ +|``bytes_restored`` | Number of bytes restored | ++----------------------+------------------------------------------------------------+ + + snapshots --------- From 229c7b24a4385d0a4397d5b9d791b2cdaf021b45 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Sat, 8 Jul 2023 23:29:46 +0200 Subject: [PATCH 6/6] doc: add program_version field of snapshot JSON output --- doc/075_scripting.rst | 104 ++++++++++++++++++++++-------------------- 1 file changed, 54 insertions(+), 50 deletions(-) diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index 85c67ab38..a4b983d7c 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -335,31 +335,33 @@ ForgetGroup Snapshot object -+----------------+--------------------------------------------------+ -| ``time`` | Timestamp of when the backup was started | -+----------------+--------------------------------------------------+ -| ``parent`` | ID of the parent snapshot | -+----------------+--------------------------------------------------+ -| ``tree`` | ID of the root tree blob | -+----------------+--------------------------------------------------+ -| ``paths`` | List of paths included in the backup | -+----------------+--------------------------------------------------+ -| ``hostname`` | Hostname of the backed up machine | -+----------------+--------------------------------------------------+ -| ``username`` | Username the backup command was run as | -+----------------+--------------------------------------------------+ -| ``uid`` | ID of owner | -+----------------+--------------------------------------------------+ -| ``gid`` | ID of group | -+----------------+--------------------------------------------------+ -| ``excludes`` | List of paths and globs excluded from the backup | -+----------------+--------------------------------------------------+ -| ``tags`` | List of tags for the snapshot in question | -+----------------+--------------------------------------------------+ -| ``id`` | Snapshot ID | -+----------------+--------------------------------------------------+ -| ``short_id`` | Snapshot ID, short form | -+----------------+--------------------------------------------------+ ++---------------------+--------------------------------------------------+ +| ``time`` | Timestamp of when the backup was started | ++---------------------+--------------------------------------------------+ +| ``parent`` | ID of the parent snapshot | ++---------------------+--------------------------------------------------+ +| ``tree`` | ID of the root tree blob | ++---------------------+--------------------------------------------------+ +| ``paths`` | List of paths included in the backup | ++---------------------+--------------------------------------------------+ +| ``hostname`` | Hostname of the backed up machine | ++---------------------+--------------------------------------------------+ +| ``username`` | Username the backup command was run as | ++---------------------+--------------------------------------------------+ +| ``uid`` | ID of owner | ++---------------------+--------------------------------------------------+ +| ``gid`` | ID of group | ++---------------------+--------------------------------------------------+ +| ``excludes`` | List of paths and globs excluded from the backup | ++---------------------+--------------------------------------------------+ +| ``tags`` | List of tags for the snapshot in question | ++---------------------+--------------------------------------------------+ +| ``program_version`` | restic version used to create snapshot | ++---------------------+--------------------------------------------------+ +| ``id`` | Snapshot ID | ++---------------------+--------------------------------------------------+ +| ``short_id`` | Snapshot ID, short form | ++---------------------+--------------------------------------------------+ Reason object @@ -518,31 +520,33 @@ snapshots The snapshots command returns a single JSON object, an array with objects of the structure outlined below. -+----------------+--------------------------------------------------+ -| ``time`` | Timestamp of when the backup was started | -+----------------+--------------------------------------------------+ -| ``parent`` | ID of the parent snapshot | -+----------------+--------------------------------------------------+ -| ``tree`` | ID of the root tree blob | -+----------------+--------------------------------------------------+ -| ``paths`` | List of paths included in the backup | -+----------------+--------------------------------------------------+ -| ``hostname`` | Hostname of the backed up machine | -+----------------+--------------------------------------------------+ -| ``username`` | Username the backup command was run as | -+----------------+--------------------------------------------------+ -| ``uid`` | ID of owner | -+----------------+--------------------------------------------------+ -| ``gid`` | ID of group | -+----------------+--------------------------------------------------+ -| ``excludes`` | List of paths and globs excluded from the backup | -+----------------+--------------------------------------------------+ -| ``tags`` | List of tags for the snapshot in question | -+----------------+--------------------------------------------------+ -| ``id`` | Snapshot ID | -+----------------+--------------------------------------------------+ -| ``short_id`` | Snapshot ID, short form | -+----------------+--------------------------------------------------+ ++---------------------+--------------------------------------------------+ +| ``time`` | Timestamp of when the backup was started | ++---------------------+--------------------------------------------------+ +| ``parent`` | ID of the parent snapshot | ++---------------------+--------------------------------------------------+ +| ``tree`` | ID of the root tree blob | ++---------------------+--------------------------------------------------+ +| ``paths`` | List of paths included in the backup | ++---------------------+--------------------------------------------------+ +| ``hostname`` | Hostname of the backed up machine | ++---------------------+--------------------------------------------------+ +| ``username`` | Username the backup command was run as | ++---------------------+--------------------------------------------------+ +| ``uid`` | ID of owner | ++---------------------+--------------------------------------------------+ +| ``gid`` | ID of group | ++---------------------+--------------------------------------------------+ +| ``excludes`` | List of paths and globs excluded from the backup | ++---------------------+--------------------------------------------------+ +| ``tags`` | List of tags for the snapshot in question | ++---------------------+--------------------------------------------------+ +| ``program_version`` | restic version used to create snapshot | ++---------------------+--------------------------------------------------+ +| ``id`` | Snapshot ID | ++---------------------+--------------------------------------------------+ +| ``short_id`` | Snapshot ID, short form | ++---------------------+--------------------------------------------------+ stats