From 6154685c3abf3d5b8c1de5c3a7fd7416745d5ea9 Mon Sep 17 00:00:00 2001 From: Winfried Plappert <18740761+wplapper@users.noreply.github.com> Date: Wed, 28 Jan 2026 16:46:14 +0000 Subject: [PATCH 1/3] docs: add documentation for `restic list` added a file doc/view_repository.rst which contains the description of `restic list ...` --- doc/100_references.rst | 1 + doc/cache.rst | 13 ++++ doc/view_repository.rst | 139 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 153 insertions(+) create mode 100644 doc/view_repository.rst diff --git a/doc/100_references.rst b/doc/100_references.rst index 4be4e0dae..a5a3f10ff 100644 --- a/doc/100_references.rst +++ b/doc/100_references.rst @@ -19,5 +19,6 @@ Design ****** .. include:: design.rst +.. include:: view_repository.rst .. include:: cache.rst .. include:: REST_backend.rst diff --git a/doc/cache.rst b/doc/cache.rst index 7b1cabebb..1ce3c78fc 100644 --- a/doc/cache.rst +++ b/doc/cache.rst @@ -1,3 +1,16 @@ +.. + Normally, there are no heading levels assigned to certain characters as the structure is + determined from the succession of headings. However, this convention is used in Python’s + Style Guide for documenting which you may follow: + + # with overline, for parts + * for chapters + = for sections + - for subsections + ^ for subsubsections + " for paragraphs + + *********** Local Cache *********** diff --git a/doc/view_repository.rst b/doc/view_repository.rst new file mode 100644 index 000000000..9d6347bf4 --- /dev/null +++ b/doc/view_repository.rst @@ -0,0 +1,139 @@ +.. + Normally, there are no heading levels assigned to certain characters as the structure is + determined from the succession of headings. However, this convention is used in Python’s + Style Guide for documenting which you may follow: + + # with overline, for parts + * for chapters + = for sections + - for subsections + ^ for subsubsections + " for paragraphs + + +######################## +Diving into a Repository +######################## + +The following chapter dives into the commands a designer or code maintainer could use +to extract certain data forom a repository. + +********************************************** +Listing different file types in the repository +********************************************** + +The ``restic list`` allows listing objects in the repository based on type. +The allowed types are (in alphabetic order): + +- blobs +- index +- keys +- locks +- packs +- snapshots + +With the exception of ``blobs`` all output - in text mode - contains zero or more +``IDs`` of the given type, one ``ID`` per output line. + +The output for ``blobs`` contains one or more lines of output of the form +``blob-type blob-ID``, where ``blob-type`` is either ``data`` or ``tree``, and ``blob-ID`` +is the ``sha256sum`` of the ``blob``. + +The output of the ``restic list 'type-plural'`` is most commonly used for the ``restic cat 'type' ID`` +command to study an ``type`` object with an ``ID`` in more detail. The only exception to +this singular/plural ``type`` is ``ìndex``, which is used in both commands ``restic list index`` and +``restic cat index ``. + +The examples below are using part of the standard file structure for testing restic itself. +Here is the ``ls`` output of the one and only snapshot in this test repository: + +.. code-block:: console + + $ restic -r /srv/restic-repo ls 4254d65c + snapshot 4254d65c of [/srv/restic-repo/testdata/0/for_cmd_ls] at 2026-01-17 17:26:41.972899252 +0000 UTC by user@kasimir filtered by []: + /srv/restic-repo/testdata + /srv/restic-repo/testdata/0 + /srv/restic-repo/testdata/0/for_cmd_ls + /srv/restic-repo/testdata/0/for_cmd_ls/file1.txt + /srv/restic-repo/testdata/0/for_cmd_ls/file2.txt + /srv/restic-repo/testdata/0/for_cmd_ls/python.py + +Inspecting this repository with ``restic list snapshots`` produces: + +.. code-block:: console + + $ restic -r /srv/restic-repo list snapshots -q + 4254d65c92208eda22b852b390bd5401ca4c500be7a022c70e7c33de68ca2143 + $ restic -r /srv/restic-repo cat snapshot 4254d65c92208eda22b852b390bd5401ca4c500be7a022c70e7c33de68ca2143 -q + { + "time": "2026-01-17T17:26:41.972899252Z", + "tree": "db9e90f7f1761ab892b3ae25e3838bbd697499b985e9b47d3a1da09e0bd8ca68", + ... + "summary": { + "backup_start": "2026-01-17T17:26:41.972899252Z", + "backup_end": "2026-01-17T17:26:42.581012438Z", + ... + } + } + +The index contains 2 packfiles, one for trees and one for the actual file data: + +.. code-block:: console + + $ restic -r /srv/restic-repo list index -q + a1828d209e760f0fd143aa79e530de0a377d7affd1cd0964d9cb2ad3c77e0d8b + $ restic -r /srv/restic-repo cat index a1828d209e760f0fd143aa79e530de0a377d7affd1cd0964d9cb2ad3c77e0d8b | jq + { + "packs": [ + { + "id": "953e5381138bdc44da23740a83065809dd4021f45ce4e351b577dc4c07f81314", + "blobs": [ + { + "id": "124323c57d74fb8944c98fb69ce67a41a107cb6d2ed304cf50c8529cc137aafd", + "type": "data", + "offset": 0, + "length": 59, + "uncompressed_length": 18 + }, + ... + ] + }, + { + "id": "75bca8556f47d16362e58e757ea89a34b28fb96aedcc314bea35d468e5cb665c", + "blobs": [ + { + "id": "6dfdc53cc3b45a6bf519a7fb80a54f6ef3e3ea859f51d3e85a6235177606f1f9", + "type": "tree", + "offset": 0, + "length": 271, + "uncompressed_length": 353 + }, + ... + ] + } + ] + } + +And this is the list of blobs: + +.. code-block:: console + + $ restic -r /srv/restic-repo list blobs -q + data 124323c57d74fb8944c98fb69ce67a41a107cb6d2ed304cf50c8529cc137aafd + data 37cc0b45af245d93abaecba73a600a8d577b39e4a1fdc2dcdf93ad63b1e167bd + data 5dfb8bc8a35175bf011d10ac7bc3a6b8d42b7743ac188be8c1bf0b215f9b7bf5 + tree 6dfdc53cc3b45a6bf519a7fb80a54f6ef3e3ea859f51d3e85a6235177606f1f9 + tree 73947e98d4025179347363401eb41f148dc29a1d1735bfb96a08a6036422108c + tree 6d1daddbb3f280be0f25e708618576e003c2a87516a9aa31e98205ae0a152ab5 + tree 2e89c815e31c377629ef77fa1c156d1ad794b9f09d9d3b113e00e8eab36ceb98 + tree db9e90f7f1761ab892b3ae25e3838bbd697499b985e9b47d3a1da09e0bd8ca68 + tree d2524f3358bffbfe7349ca73df4bd3f23f5b252a9ba887481eda7e696b506dd4 + tree 4d8f5a6c6e90a2d69ae4b2f8e4f7f5851ccc4fa2cd3314f81de6c929453994fe + +The other types ``keys``, ``locks`` and ``packs`` are used in the same way as the type ``index``. + +.. code-block:: console + + $ restic -r /srv/restic-repo list packs -q + 953e5381138bdc44da23740a83065809dd4021f45ce4e351b577dc4c07f81314 + 75bca8556f47d16362e58e757ea89a34b28fb96aedcc314bea35d468e5cb665c From 099650f8834dc497108cdcb86bfcb077bf519fa9 Mon Sep 17 00:00:00 2001 From: Winfried Plappert <18740761+wplapper@users.noreply.github.com> Date: Wed, 28 Jan 2026 17:06:18 +0000 Subject: [PATCH 2/3] docs: restic list corrected typo --- doc/view_repository.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/view_repository.rst b/doc/view_repository.rst index 9d6347bf4..12fd8b923 100644 --- a/doc/view_repository.rst +++ b/doc/view_repository.rst @@ -16,7 +16,7 @@ Diving into a Repository ######################## The following chapter dives into the commands a designer or code maintainer could use -to extract certain data forom a repository. +to extract certain data from a repository. ********************************************** Listing different file types in the repository From b544e71cac1f2cfd4b12f8eeed5d37171f5e5064 Mon Sep 17 00:00:00 2001 From: Winfried Plappert <18740761+wplapper@users.noreply.github.com> Date: Sun, 1 Feb 2026 06:12:56 +0000 Subject: [PATCH 3/3] restic list doc - documenmtation fixed wording for paragraph and inconsistent underlining --- doc/cache.rst | 13 ------------- doc/view_repository.rst | 10 ++++------ 2 files changed, 4 insertions(+), 19 deletions(-) diff --git a/doc/cache.rst b/doc/cache.rst index 1ce3c78fc..7b1cabebb 100644 --- a/doc/cache.rst +++ b/doc/cache.rst @@ -1,16 +1,3 @@ -.. - Normally, there are no heading levels assigned to certain characters as the structure is - determined from the succession of headings. However, this convention is used in Python’s - Style Guide for documenting which you may follow: - - # with overline, for parts - * for chapters - = for sections - - for subsections - ^ for subsubsections - " for paragraphs - - *********** Local Cache *********** diff --git a/doc/view_repository.rst b/doc/view_repository.rst index 12fd8b923..280446cd9 100644 --- a/doc/view_repository.rst +++ b/doc/view_repository.rst @@ -11,16 +11,14 @@ " for paragraphs -######################## +************************ Diving into a Repository -######################## - -The following chapter dives into the commands a designer or code maintainer could use +************************ +The following section dives into the commands developers could use to extract certain data from a repository. -********************************************** Listing different file types in the repository -********************************************** +============================================== The ``restic list`` allows listing objects in the repository based on type. The allowed types are (in alphabetic order):