From a99f9ef8adebdb460435d70f7bb8a0e6965c1cd3 Mon Sep 17 00:00:00 2001 From: Winfried Plappert <18740761+wplapper@users.noreply.github.com> Date: Mon, 2 Feb 2026 07:09:10 +0000 Subject: [PATCH] restic find - documentation reworked chapter about `restic find` documentation. --- doc/045_working_with_repos.rst | 109 +++++---------------------------- 1 file changed, 16 insertions(+), 93 deletions(-) diff --git a/doc/045_working_with_repos.rst b/doc/045_working_with_repos.rst index 79328ce0a..89c62049e 100644 --- a/doc/045_working_with_repos.rst +++ b/doc/045_working_with_repos.rst @@ -545,83 +545,49 @@ a file size value the following command may be used: Finding things in the repository ================================ -The ``restic find`` command searches for files and directories in snapshots stored -in the repository. You must specify a pattern ``find`` has to look for. -It can also be used to search for blobs, trees or packfiles; -when seaching for blobs, trees or packfiles an ID list must be given. - -The function and output of the ``find`` command falls into two categories: - -- searching for files and directories, use options ``--long``, ``--human-readable``, ``--reverse``, ``--ignore-case``, ``--oldest`` and ``--newest`` -- looking for ``--blob``, ``--tree`` or ``--pack`` information - -restic find options -------------------- - -+--------------------+----------------------------------------------------------+ -|``--JSON`` | produce JSON output | -+--------------------+----------------------------------------------------------+ -|``--snapshot`` | snapshot `id` to search in (can be given multiple times) | -+--------------------+----------------------------------------------------------+ -+--------------------+----------------------------------------------------------+ -| | for finding files and directories | -+--------------------+----------------------------------------------------------+ -|``--oldest`` | oldest modification date/time | -+--------------------+----------------------------------------------------------+ -|``--newest`` | newest modification date/time | -+--------------------+----------------------------------------------------------+ -|``--long`` | give a long listing of files and directories | -+--------------------+----------------------------------------------------------+ -|``--human-readable``| print sizes in human readable format | -+--------------------+----------------------------------------------------------+ -|``--reverse`` | reverse sort order of snapshots from oldest to newest | -+--------------------+----------------------------------------------------------+ -|``--ignore-case`` | ignore case for pattern | -+--------------------+----------------------------------------------------------+ -+--------------------+----------------------------------------------------------+ -| | searching for an ID list of a given type | -+--------------------+----------------------------------------------------------+ -|``--blob`` | searching for data blob(s) | -+--------------------+----------------------------------------------------------+ -|``--tree`` | searching for tree blob(s) | -+--------------------+----------------------------------------------------------+ -|``--pack`` | searching for packfile(s) | -+--------------------+----------------------------------------------------------+ -|``--show-pack-id`` | display packfile ID the blob(s) belong to (blob/tree) | -+--------------------+----------------------------------------------------------+ +The ``restic find`` command searches for files or directories stored +in the repository. find files and directories -------------------------- -If you want to find files or directories in the repository, you can issue the command +If you want to find files or directories in the repository, you either specific filename(s) +or a pattern which represents filename(s). +The use of file patterns is described in :ref:`backup-excluding-files`. +Here is an example: .. code-block:: console - $ restic -r /srv/restic-repo find 0/**/7 + $ restic -r /srv/restic-repo find "0/**/7" Found matching entries in snapshot 774ebacd from 2026-01-16 09:01:17 /srv/restic-repo/restic/testdata/0/0/9/7 -The normal ``*`` and ``**`` syntax applies to make your searches more generic. - Another interesting feature of the ``find`` command is the ability to search for files and directories which have an ``inode`` modification time in a given time interval, by using the options ``--oldest`` and ``--newest``. You don't have to give both the options, a half open interval is perfectly acceptable. +The following example searches for files which have a modification date in the year 2025. .. code-block:: console - $ restic -r /srv/restic-repo find --oldest 2025-01-01 --newest 2025-12-31 + $ restic -r /srv/restic-repo find --oldest 2025-01-01 --newest "2025-12-31 23:59:59" Found matching entries in snapshot dd90f84d from 2026-01-17 17:26:41 /srv/restic-repo/restic/testdata/0/for_cmd_ls /srv/restic-repo/restic/testdata/0/for_cmd_ls/file1.txt /srv/restic-repo/restic/testdata/0/for_cmd_ls/file2.txt /srv/restic-repo/restic/testdata/0/for_cmd_ls/python.py +All these commands work in ``--JSON`` mode as well, for output details for the +various options please refer to :ref:`find`. + find blobs, trees or packfiles ------------------------------ The other options of the ``find`` command are devoted to finding blobs, trees and packfiles. -If you are looking for specific data blob(s), you can issue the command: +These are typically not used by the normal user, but can help debugging a problem +with restic. See :ref:`troubleshooting` for more details there. + +Just one quick example: if you are looking for specific data blob(s), you can issue the command: .. code-block:: console @@ -631,49 +597,6 @@ If you are looking for specific data blob(s), you can issue the command: (tree 6409bed28d08898b849ecc4fdf338cdb0d67358619c99e6f6c3b402b1895baf8) ... in snapshot 774ebacd (2026-01-16 09:01:17) -If you want to know to which packfile your selected data blob belongs to, add -``--show-pack-id`` to your command line: - -.. code-block:: console - - $ restic -r /srv/restic-repo find --blob fcd9ec0c --show-pack-id - Found blob fcd9ec0c99f7992c184666e3040831b919f3375157bd563a2b65cde1c6789847 - ... in file /srv/restic-repo/restic/testdata/0/0/9/60 - (tree 6409bed28d08898b849ecc4fdf338cdb0d67358619c99e6f6c3b402b1895baf8) - ... in snapshot 774ebacd (2026-01-16 09:01:17) - Object belongs to pack 433d47eae0872558f648f6db0caf36fe703d153750b6a25d594047830dff513a - ... Pack 433d47ea: - -If you are interested in specific tree blob(s), use the ``--tree`` option: - -.. code-block:: console - - $ restic -r /srv/restic-repo find --tree fcd9ec0c --show-pack-id - Found tree 6409bed28d08898b849ecc4fdf338cdb0d67358619c99e6f6c3b402b1895baf8 - ... path /srv/restic-repo/restic/testdata/0/0/9 - ... in snapshot 774ebacd (2026-01-16 09:01:17) - -Showing the contents of a packfile can produce a lot of output, but this is a -short example: - -.. code-block:: console - - $ restic -r /srv/restic-repo find --pack 25362373 - Found blob 37cc0b45af245d93abaecba73a600a8d577b39e4a1fdc2dcdf93ad63b1e167bd - ... in file /home/wplapper/restic/testdata/0/for_cmd_ls/file1.txt - (tree 6d1daddbb3f280be0f25e708618576e003c2a87516a9aa31e98205ae0a152ab5) - ... in snapshot dd90f84d (2026-01-17 17:26:41) - Found blob 124323c57d74fb8944c98fb69ce67a41a107cb6d2ed304cf50c8529cc137aafd - ... in file /home/wplapper/restic/testdata/0/for_cmd_ls/file2.txt - (tree 6d1daddbb3f280be0f25e708618576e003c2a87516a9aa31e98205ae0a152ab5) - ... in snapshot dd90f84d (2026-01-17 17:26:41) - Found blob 5dfb8bc8a35175bf011d10ac7bc3a6b8d42b7743ac188be8c1bf0b215f9b7bf5 - ... in file /home/wplapper/restic/testdata/0/for_cmd_ls/python.py - (tree 6d1daddbb3f280be0f25e708618576e003c2a87516a9aa31e98205ae0a152ab5) - ... in snapshot dd90f84d (2026-01-17 17:26:41) - -All these commands work in ``--JSON`` mode as well, for output details for the -various options please look at section :ref:`find` in the chapter :ref:`JSON output`. Upgrading the repository format version =======================================