doc: deprecate short_id and add some missing fields

cmd/restic/cmd_ls.go

@@ -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
 	}

cmd/restic/cmd_snapshots.go

@@ -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.

doc/075_scripting.rst

@@ -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: