amorfo77/restic
1
0
Fork 0
mirror of https://github.com/restic/restic.git synced 2026-06-01 14:49:44 +00:00
Code Issues Projects Releases Wiki Activity

docs: expand restic cat documentation (#5679)

Browse Source 
Co-authored-by: Michael Eischer <michael.eischer@fau.de>
This commit is contained in:
MetalSpork
2026-05-31 08:46:45 -07:00
committed by GitHub
parent 474c094cac
commit 042feb2b7f
5 changed files with 367 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/075_scripting.rst
+3 -4
View File
@@ -359,10 +359,9 @@ Summary is the last output line in a successful backup.
cat
---
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.
The ``cat`` command is used to inspect and print internal repository objects to stdout.
This is primarily useful for debugging, understanding repository structure, or
recovering data from a damaged repository. For details refer to the :ref:`view-repository-objects` section.
check
-----
doc/090_participating.rst
+1 -1
View File
@@ -96,7 +96,7 @@ your ideas and design first.
More information and a description of the development environment can be
found in `CONTRIBUTING.md <https://github.com/restic/restic/blob/master/CONTRIBUTING.md>`__.
A document describing the design of restic and the data structures stored on the
back end is contained in `Design <https://restic.readthedocs.io/en/latest/design.html>`__.
back end is contained in :ref:`repository-format`.
If you'd like to start contributing to restic, but don't know exactly
what to do, have a look at this great article by Dave Cheney:
doc/conf.py
+10 -1
View File
@@ -61,7 +61,16 @@ language = "en"
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
exclude_patterns = [
'_build',
'Thumbs.db',
'.DS_Store',
# Included only via 100_references.rst (avoids duplicate labels).
'design.rst',
'view_repository.rst',
'cache.rst',
'REST_backend.rst',
]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
doc/design.rst
+2
View File
@@ -23,6 +23,8 @@ or the directory and its contents.
the repository. This ID is required in order to load the file from the
repository.
.. _repository-format:
Repository Format
=================
doc/view_repository.rst
+351
View File
@@ -135,3 +135,354 @@ The other types ``keys``, ``locks`` and ``packs`` are used in the same way as th
$ restic -r /srv/restic-repo list packs -q
953e5381138bdc44da23740a83065809dd4021f45ce4e351b577dc4c07f81314
75bca8556f47d16362e58e757ea89a34b28fb96aedcc314bea35d468e5cb665c
.. _view-repository-objects:
Inspecting repository objects
=============================
The ``cat`` command is used to inspect and print internal repository objects to stdout.
This is primarily useful for debugging, understanding repository structure, or
recovering data from a damaged repository. The command supports the object types described
below. To get a list of objects of a given type, use the ``restic list`` command
as described in the previous section.
For details about the individual data structures, see the :ref:`repository-format` section.
.. note::
The output format for ``masterkey``, ``config``, ``snapshot``, ``tree``, ``index``,
``key``, and ``lock`` is JSON. The output for ``blob`` and ``pack`` is raw
binary data. If the output of ``cat`` is sent to a file or command, or when specifying
``--json`` or ``--quiet``, then any extra messages that the command generates on stdout
will be suppressed. Errors are still printed on stderr.
masterkey
---------
Prints the master encryption key in JSON format. This contains the master
encryption and message authentication keys for the repository (encoded in Base64).
No additional ID argument is required.
Example::
$ restic -r /srv/restic-repo cat masterkey
repository c528f271 opened (version 2, compression level auto)
{
"mac": {
"k": "...omitted base64...",
"r": "...omitted base64..."
},
"encrypt": "...omitted base64..."
}
config
------
Prints the repository configuration in JSON format. This includes settings such as
the repository version and chunker polynomial. No additional ID argument is required.
Example::
$ restic -r /srv/restic-repo cat config
repository c528f271 opened (version 2, compression level auto)
{
"version": 2,
"id": "c528f27103c1cfc08ca3df9331c5b04a73b9c6822ae30f33bbf1d9342b9a1bf0",
"chunker_polynomial": "255b9ca195d755"
}
snapshot ID
-----------
Prints the metadata for a specific snapshot in JSON format. The snapshot ID
can be the full snapshot ID or a unique prefix. The output includes the
snapshot timestamp, paths, tags, hostname, username, and the root tree ID,
and a number of additional fields.
Example::
$ restic -r /srv/restic-repo cat snapshot 251c2e58
repository c528f271 opened (version 2, compression level auto)
{
"time": "2026-02-19T22:44:34.833377676-08:00",
"parent": "b204fa5c0a8d3cd37fd97b23d0bf20e9c1c0a2144c609ecbf5ce62bb264e0e14",
"tree": "eff44e81e07d4ffbb50c5e7012b4d74fce63c19791cab62a6e8df387fd71e1dd",
"paths": [
"/home/myuser/test-assets"
],
"hostname": "myhost",
"username": "myuser",
"uid": 1000,
"gid": 1000,
"tags": [
"assets"
],
"program_version": "restic 0.18.1",
"summary": {
"backup_start": "2026-02-19T22:44:34.833377676-08:00",
"backup_end": "2026-02-19T22:44:35.510749043-08:00",
"files_new": 0,
"files_changed": 0,
"files_unmodified": 32,
"dirs_new": 0,
"dirs_changed": 0,
"dirs_unmodified": 17,
"data_blobs": 0,
"tree_blobs": 0,
"data_added": 0,
"data_added_packed": 0,
"total_files_processed": 32,
"total_bytes_processed": 2525938
}
}
tree snapshot[:subfolder]
-------------------------
Prints the root tree of a snapshot or a specific subfolder if specified.
This outputs the tree in JSON format. The tree contains nodes representing files
and directories. To view the tree structure in a human-readable format, you can
use the ``restic ls`` command instead. For better readability, pipe the output
to ``jq``.
Example::
# Print the root tree of a snapshot
$ restic -r /srv/restic-repo cat tree 251c2e584489c16e19f3c4544a0ef23e3ebf65a7cc23c68f31035ddf885d92ad | jq .
{
"nodes": [
{
"name": "test-assets",
"type": "dir",
"mode": 2147484141,
"mtime": "2026-02-19T22:14:58.41375581-08:00",
"atime": "2026-02-19T22:14:58.41375581-08:00",
"ctime": "2026-02-19T22:14:58.41375581-08:00",
"uid": 1000,
"gid": 1000,
"user": "myuser",
"group": "mygroup",
"inode": 1698305,
"device_id": 41,
"content": null,
"subtree": "2f15b17652357a2be758e58a76549eda0f7fb155d9a7bf3081234d8a028601ac"
}
]
}
# Print a specific subfolder within a snapshot
$ restic -r /srv/restic-repo cat tree 251c2e584489c16e19f3c4544a0ef23e3ebf65a7cc23c68f31035ddf885d92ad:subfolder/path | jq .
{
"nodes": [
{
"name": ".git",
"type": "dir",
"mode": 2147484141,
"mtime": "2026-02-19T22:14:58.415878457-08:00",
"atime": "2026-02-19T22:14:58.415878457-08:00",
"ctime": "2026-02-19T22:14:58.415878457-08:00",
"uid": 1000,
"gid": 1000,
"user": "myuser",
"group": "mygroup",
"inode": 1698306,
"device_id": 41,
"content": null,
"subtree": "7e85cd4922528fac27879965a4ffa64d52ad912b14f1e23e788f5de432ed2072"
},
{
"name": "README.md",
"type": "file",
"mode": 420,
"mtime": "2026-02-19T22:14:58.411265656-08:00",
"atime": "2026-02-19T22:14:58.411265656-08:00",
"ctime": "2026-02-19T22:14:58.411265656-08:00",
"uid": 1000,
"gid": 1000,
"user": "myuser",
"group": "mygroup",
"inode": 1698370,
"device_id": 41,
"size": 50,
"links": 1,
"content": [
"0499644cc8e5f947be5df73c15b673b96067631d213c751b51951d65fad7b3f4"
]
},
...additional output omitted...
]
}
blob ID
-------
Prints the raw binary content of a blob (data or tree). The ID can be
either a data blob or a tree blob. The output is the decrypted content in its
original binary format. For tree blobs, you can pipe the output to ``jq`` for
readable JSON.
Example::
# Print a tree blob and view as JSON (requires jq)
$ restic -r /srv/restic-repo cat blob 2f15b17652357a2be758e58a76549eda0f7fb155d9a7bf3081234d8a028601ac | jq .
{
"nodes": [
{
"name": ".git",
"type": "dir",
"mode": 2147484141,
"mtime": "2026-02-19T22:14:58.415878457-08:00",
"atime": "2026-02-19T22:14:58.415878457-08:00",
"ctime": "2026-02-19T22:14:58.415878457-08:00",
"uid": 1000,
"gid": 1000,
"user": "myuser",
"group": "mygroup",
"inode": 1698306,
"device_id": 41,
"content": null,
"subtree": "7e85cd4922528fac27879965a4ffa64d52ad912b14f1e23e788f5de432ed2072"
},
{
"name": "README.md",
"type": "file",
"mode": 420,
"mtime": "2026-02-19T22:14:58.411265656-08:00",
"atime": "2026-02-19T22:14:58.411265656-08:00",
"ctime": "2026-02-19T22:14:58.411265656-08:00",
"uid": 1000,
"gid": 1000,
"user": "myuser",
"group": "mygroup",
"inode": 1698370,
"device_id": 41,
"size": 50,
"links": 1,
"content": [
"0499644cc8e5f947be5df73c15b673b96067631d213c751b51951d65fad7b3f4"
]
},
...additional output omitted...
]
}
# Print a data blob
$ restic -r /srv/restic-repo cat blob 0499644cc8e5f947be5df73c15b673b96067631d213c751b51951d65fad7b3f4
repository c528f271 opened (version 2, compression level auto)
[0:00] 100.00% 1 / 1 index files loaded
[blob contents]
# Print a data blob and verify the hash
$ restic -r /srv/restic-repo cat blob 0499644cc8e5f947be5df73c15b673b96067631d213c751b51951d65fad7b3f4 | sha256sum
0499644cc8e5f947be5df73c15b673b96067631d213c751b51951d65fad7b3f4 -
index ID
--------
Prints the index file content in JSON format. The index maps blobs to pack files
that contain them.
Example::
$ restic -r /srv/restic-repo cat index c3c0855e22febcfbd3897a2b8bd84c2c0d0356fffe93744c5a853bf453f3e921 | jq .
{
"packs": [
{
"id": "fe975e242e458b2c18bd00538ae16eaba3077fe1b615b00366294c0c3a52c664",
"blobs": [
{
"id": "0223497a0b8b033aa58a3a521b8629869386cf7ab0e2f101963d328aa62193f7",
"type": "data",
"offset": 0,
"length": 328,
"uncompressed_length": 478
},
{
"id": "81765af2daef323061dcbc5e61fc16481cb74b3bac9ad8a174b186523586f6c5",
"type": "data",
"offset": 328,
"length": 181,
"uncompressed_length": 189
},
...additional similarly structured objects omitted...
]
},
{
"id": "d558c02687114c0a0cb060d0a0e49f7f0fcdda4c86790bedae49025f88059ee0",
"blobs": [
{
"id": "59f06b13a43d7bf7fcaccef0c47b23c9d129901bead6901ff8776f14c126fadb",
"type": "tree",
"offset": 0,
"length": 258,
"uncompressed_length": 377
},
{
"id": "7a82ac2ee96828b667155f3255bbcc15af06740df6bad5513bc1159e28e2cfef",
"type": "tree",
"offset": 258,
"length": 261,
"uncompressed_length": 375
},
...additional similarly structured objects omitted...
]
}
]
}
key ID
------
Prints information about a specific key in JSON format. This includes the key
creation time, username, hostname, and the encrypted master key data.
Example::
$ restic -r /srv/restic-repo cat key 33aa6685814c417df6eca8dfd5cbf7e0000dd197cdda223aa9443190b619e5c7
repository c528f271 opened (version 2, compression level auto)
{
"created": "2026-02-19T22:16:30.938425666-08:00",
"username": "myuser",
"hostname": "myhost",
"kdf": "scrypt",
"N": 32768,
"r": 8,
"p": 5,
"salt": "...omitted...",
"data": "...omitted..."
}
lock ID
-------
Prints information about a repository lock in JSON format. Locks are created
during repository operations to prevent concurrent access.
Example::
$ restic -r /srv/restic-repo cat lock 623da7f58063e4acd52a9995049e96b83a7ab39d158304ec83e3554c33bcbf63
repository c528f271 opened (version 2, compression level auto)
{
"time": "2026-02-19T22:37:46.85328066-08:00",
"exclusive": false,
"hostname": "myhost",
"username": "myuser",
"pid": 1698519,
"uid": 1000,
"gid": 1000
}
pack ID
-------
Prints the raw binary content of a pack file. Pack files contain multiple
encrypted blobs and are the fundamental storage unit in restic. The command
will verify the hash and warn if it doesn't match the pack ID.
Example::
$ restic -r /srv/restic-repo cat pack fe975e242e458b2c18bd00538ae16eaba3077fe1b615b00366294c0c3a52c664
[binary output]