diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index 1ed51ad82..70bde985e 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -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 ----- diff --git a/doc/090_participating.rst b/doc/090_participating.rst index d6d474b23..30c885308 100644 --- a/doc/090_participating.rst +++ b/doc/090_participating.rst @@ -96,7 +96,7 @@ your ideas and design first. More information and a description of the development environment can be found in `CONTRIBUTING.md `__. A document describing the design of restic and the data structures stored on the -back end is contained in `Design `__. +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: diff --git a/doc/conf.py b/doc/conf.py index 6c89d0f41..9aa03d1b5 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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' diff --git a/doc/design.rst b/doc/design.rst index e526d4970..21a560e49 100644 --- a/doc/design.rst +++ b/doc/design.rst @@ -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 ================= diff --git a/doc/view_repository.rst b/doc/view_repository.rst index 1ec752e34..26000f978 100644 --- a/doc/view_repository.rst +++ b/doc/view_repository.rst @@ -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]