mirror/restic
1
0
Fork 0
mirror of https://github.com/restic/restic.git synced 2025-03-04 02:28:27 +00:00
Code Issues Releases Wiki Activity

doc: deprecate short_id and add some missing fields

Browse source
This commit is contained in:
Michael Eischer 2025-02-06 20:53:01 +01:00
parent 421842f41f
commit 39823c5f6c
3 changed files with 113 additions and 99 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
cmd/restic/cmd_ls.go
View file

@ -100,7 +100,7 @@ func (p *jsonLsPrinter) Snapshot(sn *restic.Snapshot) error {
type lsSnapshot struct { type lsSnapshot struct {
*restic.Snapshot *restic.Snapshot
ID *restic.ID `json:"id"` ID *restic.ID `json:"id"`
ShortID string `json:"short_id"` ShortID string `json:"short_id"` // deprecated
MessageType string `json:"message_type"` // "snapshot" MessageType string `json:"message_type"` // "snapshot"
StructType string `json:"struct_type"` // "snapshot", deprecated StructType string `json:"struct_type"` // "snapshot", deprecated
} }

2
cmd/restic/cmd_snapshots.go
View file

@ -324,7 +324,7 @@ type Snapshot struct {
*restic.Snapshot *restic.Snapshot
ID *restic.ID `json:"id"` ID *restic.ID `json:"id"`
ShortID string `json:"short_id"` ShortID string `json:"short_id"` // deprecated
} }
// SnapshotGroup helps to print SnapshotGroups as JSON with their GroupReasons included. // SnapshotGroup helps to print SnapshotGroups as JSON with their GroupReasons included.

208
doc/075_scripting.rst
View file

@ -148,27 +148,27 @@ The ``backup`` command uses the JSON lines format with the following message typ
Status Status
^^^^^^ ^^^^^^
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
| ``message_type`` | Always "status" | string | | ``message_type`` | Always "status" | string |
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
| ``seconds_elapsed`` | Time since backup started | uint64 | | ``seconds_elapsed`` | Time since backup started | uint64 |
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
| ``seconds_remaining`` | Estimated time remaining | uint64 | | ``seconds_remaining`` | Estimated time remaining | uint64 |
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
| ``percent_done`` | Percentage of data backed up (bytes_done/total_bytes) | float64 | | ``percent_done`` | Fraction of data backed up (bytes_done/total_bytes) | float64 |
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
| ``total_files`` | Total number of files detected | uint64 | | ``total_files`` | Total number of files detected | uint64 |
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
| ``files_done`` | Files completed (backed up to repo) | uint64 | | ``files_done`` | Files completed (backed up to repo) | uint64 |
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
| ``total_bytes`` | Total number of bytes in backup set | uint64 | | ``total_bytes`` | Total number of bytes in backup set | uint64 |
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
| ``bytes_done`` | Number of bytes completed (backed up to repo) | uint64 | | ``bytes_done`` | Number of bytes completed (backed up to repo) | uint64 |
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
| ``error_count`` | Number of errors | uint64 | | ``error_count`` | Number of errors | uint64 |
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
| ``current_files`` | List of files currently being backed up | []string | | ``current_files`` | List of files currently being backed up | []string |
+-----------------------+-------------------------------------------------------+----------+ +-----------------------+-----------------------------------------------------+----------+
Error Error
^^^^^ ^^^^^
@ -190,21 +190,25 @@ Verbose Status
Verbose status provides details about the progress, including details about backed up files. Verbose status provides details about the progress, including details about backed up files.
+-------------------+----------------------------------------------------------+---------+ +---------------------------+----------------------------------------------------------+---------+
| ``message_type`` | Always "verbose_status" | string | | ``message_type`` | Always "verbose_status" | string |
+-------------------+----------------------------------------------------------+---------+ +---------------------------+----------------------------------------------------------+---------+
| ``action`` | Either "new", "unchanged", "modified" or "scan_finished" | string | | ``action`` | Either "new", "unchanged", "modified" or "scan_finished" | string |
+-------------------+----------------------------------------------------------+---------+ +---------------------------+----------------------------------------------------------+---------+
| ``item`` | The item in question | string | | ``item`` | The item in question | string |
+-------------------+----------------------------------------------------------+---------+ +---------------------------+----------------------------------------------------------+---------+
| ``duration`` | How long it took, in seconds | float64 | | ``duration`` | How long it took, in seconds | float64 |
+-------------------+----------------------------------------------------------+---------+ +---------------------------+----------------------------------------------------------+---------+
| ``data_size`` | How big the item is | uint64 | | ``data_size`` | How big the item is | uint64 |
+-------------------+----------------------------------------------------------+---------+ +---------------------------+----------------------------------------------------------+---------+
| ``metadata_size`` | How big the metadata is | uint64 | | ``data_size_in_repo`` | How big the item is in the repository | uint64 |
+-------------------+----------------------------------------------------------+---------+ +---------------------------+----------------------------------------------------------+---------+
| ``total_files`` | Total number of files | uint64 | | ``metadata_size`` | How big the metadata is | uint64 |
+-------------------+----------------------------------------------------------+---------+ +---------------------------+----------------------------------------------------------+---------+
| ``metadata_size_in_repo`` | How big the metadata is in the repository | uint64 |
+---------------------------+----------------------------------------------------------+---------+
| ``total_files`` | Total number of files | uint64 |
+---------------------------+----------------------------------------------------------+---------+
Summary Summary
^^^^^^^ ^^^^^^^
@ -214,6 +218,8 @@ Summary is the last output line in a successful backup.
+---------------------------+------------------------------------------------------+---------------+ +---------------------------+------------------------------------------------------+---------------+
| ``message_type`` | Always "summary" | string | | ``message_type`` | Always "summary" | string |
+---------------------------+------------------------------------------------------+---------------+ +---------------------------+------------------------------------------------------+---------------+
| ``dry_run`` | Whether the backup was a dry run | bool |
+---------------------------+------------------------------------------------------+---------------+
| ``files_new`` | Number of new files | uint64 | | ``files_new`` | Number of new files | uint64 |
+---------------------------+------------------------------------------------------+---------------+ +---------------------------+------------------------------------------------------+---------------+
| ``files_changed`` | Number of files that changed | uint64 | | ``files_changed`` | Number of files that changed | uint64 |
@ -371,6 +377,8 @@ Match object
+-----------------+----------------------------------------------+-------------+ +-----------------+----------------------------------------------+-------------+
| ``permissions`` | UNIX permissions | string | | ``permissions`` | UNIX permissions | string |
+-----------------+----------------------------------------------+-------------+ +-----------------+----------------------------------------------+-------------+
| ``name`` | Object name | string |
+-----------------+----------------------------------------------+-------------+
| ``type`` | Object type e.g. file, dir, etc... | string | | ``type`` | Object type e.g. file, dir, etc... | string |
+-----------------+----------------------------------------------+-------------+ +-----------------+----------------------------------------------+-------------+
| ``atime`` | Access time | time.Time | | ``atime`` | Access time | time.Time |
@ -379,8 +387,6 @@ Match object
+-----------------+----------------------------------------------+-------------+ +-----------------+----------------------------------------------+-------------+
| ``ctime`` | Change time | time.Time | | ``ctime`` | Change time | time.Time |
+-----------------+----------------------------------------------+-------------+ +-----------------+----------------------------------------------+-------------+
| ``name`` | Object name | string |
+-----------------+----------------------------------------------+-------------+
| ``user`` | Name of owner | string | | ``user`` | Name of owner | string |
+-----------------+----------------------------------------------+-------------+ +-----------------+----------------------------------------------+-------------+
| ``group`` | Name of group | string | | ``group`` | Name of group | string |
@ -393,6 +399,8 @@ Match object
+-----------------+----------------------------------------------+-------------+ +-----------------+----------------------------------------------+-------------+
| ``links`` | Number of hardlinks | uint64 | | ``links`` | Number of hardlinks | uint64 |
+-----------------+----------------------------------------------+-------------+ +-----------------+----------------------------------------------+-------------+
| ``link_target`` | Target of a symlink | string |
+-----------------+----------------------------------------------+-------------+
| ``uid`` | ID of owner | uint32 | | ``uid`` | ID of owner | uint32 |
+-----------------+----------------------------------------------+-------------+ +-----------------+----------------------------------------------+-------------+
| ``gid`` | ID of group | uint32 | | ``gid`` | ID of group | uint32 |
@ -449,33 +457,35 @@ ForgetGroup
Snapshot object Snapshot object
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``time`` | Timestamp of when the backup was started | time.Time | | ``time`` | Timestamp of when the backup was started | time.Time |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``parent`` | ID of the parent snapshot | string | | ``parent`` | ID of the parent snapshot | string |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``tree`` | ID of the root tree blob | string | | ``tree`` | ID of the root tree blob | string |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``paths`` | List of paths included in the backup | []string | | ``paths`` | List of paths included in the backup | []string |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``hostname`` | Hostname of the backed up machine | string | | ``hostname`` | Hostname of the backed up machine | string |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``username`` | Username the backup command was run as | string | | ``username`` | Username the backup command was run as | string |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``uid`` | ID of owner | uint32 | | ``uid`` | ID of owner | uint32 |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``gid`` | ID of group | uint32 | | ``gid`` | ID of group | uint32 |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``excludes`` | List of paths and globs excluded from the backup | []string | | ``excludes`` | List of paths and globs excluded from the backup | []string |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``tags`` | List of tags for the snapshot in question | []string | | ``tags`` | List of tags for the snapshot in question | []string |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``program_version`` | restic version used to create snapshot | string | | ``program_version`` | restic version used to create snapshot | string |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``id`` | Snapshot ID | string | | ``summary`` | Snapshot statistics | `SnapshotSummary object`_ |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``short_id`` | Snapshot ID, short form | string | | ``id`` | Snapshot ID | string |
+---------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``short_id`` | Snapshot ID, short form (deprecated) | string |
+---------------------+--------------------------------------------------+---------------------------+
.. _KeepReason object: .. _KeepReason object:
@ -486,8 +496,6 @@ KeepReason object
+--------------+--------------------------------------------------------+--------------------+ +--------------+--------------------------------------------------------+--------------------+
| ``matches`` | Array containing descriptions of the matching criteria | []string | | ``matches`` | Array containing descriptions of the matching criteria | []string |
+--------------+--------------------------------------------------------+--------------------+ +--------------+--------------------------------------------------------+--------------------+
| ``counters`` | Object containing counters used by the policies | object |
+--------------+--------------------------------------------------------+--------------------+
init init
@ -533,35 +541,39 @@ As an exception, the ``struct_type`` field is used to determine the message type
snapshot snapshot
^^^^^^^^ ^^^^^^^^
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``message_type`` | Always "snapshot" | string | | ``message_type`` | Always "snapshot" | string |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``struct_type`` | Always "snapshot" (deprecated) | string | | ``struct_type`` | Always "snapshot" (deprecated) | string |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``time`` | Timestamp of when the backup was started | time.Time | | ``time`` | Timestamp of when the backup was started | time.Time |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``parent`` | ID of the parent snapshot | string | | ``parent`` | ID of the parent snapshot | string |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``tree`` | ID of the root tree blob | string | | ``tree`` | ID of the root tree blob | string |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``paths`` | List of paths included in the backup | []string | | ``paths`` | List of paths included in the backup | []string |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``hostname`` | Hostname of the backed up machine | string | | ``hostname`` | Hostname of the backed up machine | string |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``username`` | Username the backup command was run as | string | | ``username`` | Username the backup command was run as | string |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``uid`` | ID of owner | uint32 | | ``uid`` | ID of owner | uint32 |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``gid`` | ID of group | uint32 | | ``gid`` | ID of group | uint32 |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``excludes`` | List of paths and globs excluded from the backup | []string | | ``excludes`` | List of paths and globs excluded from the backup | []string |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``tags`` | List of tags for the snapshot in question | []string | | ``tags`` | List of tags for the snapshot in question | []string |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``id`` | Snapshot ID | string | | ``program_version`` | restic version used to create snapshot | string |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``short_id`` | Snapshot ID, short form | string | | ``summary`` | Snapshot statistics | `SnapshotSummary object`_ |
+------------------+--------------------------------------------------+-----------+ +---------------------+--------------------------------------------------+---------------------------+
| ``id`` | Snapshot ID | string |
+---------------------+--------------------------------------------------+---------------------------+
| ``short_id`` | Snapshot ID, short form (deprecated) | string |
+---------------------+--------------------------------------------------+---------------------------+
node node
@ -586,6 +598,8 @@ node
+------------------+----------------------------+-------------+ +------------------+----------------------------+-------------+
| ``mode`` | Node mode | os.FileMode | | ``mode`` | Node mode | os.FileMode |
+------------------+----------------------------+-------------+ +------------------+----------------------------+-------------+
| ``permissions`` | Node mode as string | string |
+------------------+----------------------------+-------------+
| ``atime`` | Node access time | time.Time | | ``atime`` | Node access time | time.Time |
+------------------+----------------------------+-------------+ +------------------+----------------------------+-------------+
| ``mtime`` | Node modification time | time.Time | | ``mtime`` | Node modification time | time.Time |
@ -713,7 +727,7 @@ The snapshots command returns a single JSON array with objects of the structure
+---------------------+--------------------------------------------------+---------------------------+ +---------------------+--------------------------------------------------+---------------------------+
| ``id`` | Snapshot ID | string | | ``id`` | Snapshot ID | string |
+---------------------+--------------------------------------------------+---------------------------+ +---------------------+--------------------------------------------------+---------------------------+
| ``short_id`` | Snapshot ID, short form | string | | ``short_id`` | Snapshot ID, short form (deprecated) | string |
+---------------------+--------------------------------------------------+---------------------------+ +---------------------+--------------------------------------------------+---------------------------+
.. _SnapshotSummary object: .. _SnapshotSummary object: