From c5e09ae9b1aaedbccf09ebf7aca3d9788c7d1222 Mon Sep 17 00:00:00 2001
From: Winfried Plappert <18740761+wplapper@users.noreply.github.com>
Date: Thu, 19 Feb 2026 18:07:05 +0000
Subject: [PATCH] docs: expand restic find - documentation (#5675)

---
 doc/045_working_with_repos.rst | 53 ++++++++++++++++++++++++++++++++++
 doc/075_scripting.rst          |  8 +++--
 2 files changed, 58 insertions(+), 3 deletions(-)

diff --git a/doc/045_working_with_repos.rst b/doc/045_working_with_repos.rst
index ba263fd31..f03674383 100644
--- a/doc/045_working_with_repos.rst
+++ b/doc/045_working_with_repos.rst
@@ -542,6 +542,59 @@ a file size value the following command may be used:
     $ restic -r /srv/restic-repo check --read-data-subset=50M
     $ restic -r /srv/restic-repo check --read-data-subset=10G
 
+Finding things in the repository
+================================
+
+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 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"
+    Found matching entries in snapshot 774ebacd from 2026-01-16 09:01:17
+    /srv/restic-repo/restic/testdata/0/0/9/7
+
+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 23:59:59" "*.txt"
+    Found matching entries in snapshot dd90f84d from 2026-01-17 17:26:41
+    /srv/restic-repo/restic/testdata/0/for_cmd_ls/file1.txt
+    /srv/restic-repo/restic/testdata/0/for_cmd_ls/file2.txt
+
+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.
+These are typically not used by the normal user, but can help debugging a problem
+with restic. See :ref:`troubleshooting` for a more automated way to repair repositories.
+
+Just one quick example: if you are looking for specific data blob(s), you can issue the command:
+
+.. code-block:: console
+
+    $ restic -r /srv/restic-repo find --blob fcd9ec0c
+    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)
+
 
 Upgrading the repository format version
 =======================================
diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst
index a24e597dd..f0c225d84 100644
--- a/doc/075_scripting.rst
+++ b/doc/075_scripting.rst
@@ -161,6 +161,8 @@ a more specific description.
 | 130 | Restic was interrupted using SIGINT or SIGSTOP     |
 +-----+----------------------------------------------------+
 
+.. _JSON output:
+
 JSON output
 ***********
 
@@ -439,6 +441,7 @@ DiffStat object
 | ``bytes``      | Number of bytes                           | uint64 |
 +----------------+-------------------------------------------+--------+
 
+.. _find:
 
 find
 ----
@@ -446,9 +449,8 @@ find
 The ``find`` command outputs a single JSON document containing an array of JSON
 objects with matches for your search term.  These matches are organized by snapshot.
 
-If the ``--blob`` or ``--tree`` option is passed, then the output is an array of
-`Blob objects`_.
-
+If the ``--blob``, ``--tree`` or ``--pack`` option is passed, then the output is
+an array of `Blob objects`_.
 
 +--------------+-----------------------------------+--------------------+
 | ``hits``     | Number of matches in the snapshot | uint64             |