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 {
*restic.Snapshot
ID *restic.ID `json:"id"`
ShortID string `json:"short_id"`
ShortID string `json:"short_id"` // deprecated
MessageType string `json:"message_type"` // "snapshot"
StructType string `json:"struct_type"` // "snapshot", deprecated
}

2
cmd/restic/cmd_snapshots.go
View file

@ -324,7 +324,7 @@ type Snapshot struct {
*restic.Snapshot
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.

126
doc/075_scripting.rst
View file

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