From 9a0432a5d7efa16f89fc8d26d5e97a789093f31d Mon Sep 17 00:00:00 2001
From: Adrian Mastronardi <7809331+AdrianMastronardi@users.noreply.github.com>
Date: Wed, 13 May 2026 21:25:36 +0100
Subject: [PATCH] docs: clarify double-asterisk wildcard behavior in exclude
 patterns (#5726)

---
 doc/040_backup.rst | 33 +++++++++++++++++++++++++++++++++
 doc/faq.rst        |  2 +-
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/doc/040_backup.rst b/doc/040_backup.rst
index ad7deb3d9..3ccf5d39c 100644
--- a/doc/040_backup.rst
+++ b/doc/040_backup.rst
@@ -378,6 +378,7 @@ This instructs restic to exclude files matching the following criteria:
 
 Patterns use the syntax of the Go function
 `filepath.Match <https://pkg.go.dev/path/filepath#Match>`__
+with the addition of the double-asterisk (``**``) wildcard,
 and are tested against the full path of a file/dir to be saved,
 even if restic is passed a relative path to save. Empty lines and lines
 starting with a ``#`` are ignored.
@@ -408,6 +409,38 @@ The ``**`` must be positioned between path separators. The pattern
 * ``/foo/bar/file``
 * ``/tmp/foo/bar``
 
+For example, given the following directory structure::
+
+    /home/user/repos
+    ├── repo1
+    │   ├── target
+    │   └── src
+    ├── repo2_workspace
+    │   ├── project1
+    │   │   ├── target
+    │   │   └── src
+    │   └── project2
+    │       ├── target
+    │       └── src
+    └── repo3
+        ├── bin
+        └── src
+
+Using ``--exclude '/home/user/repos/**/target'`` will exclude all ``target``
+directories at any depth, resulting in the following backup::
+
+    /home/user/repos
+    ├── repo1
+    │   └── src
+    ├── repo2_workspace
+    │   ├── project1
+    │   │   └── src
+    │   └── project2
+    │       └── src
+    └── repo3
+        ├── bin
+        └── src
+
 Spaces in patterns listed in an exclude file can be specified verbatim. That is,
 in order to exclude a file named ``foo bar star.txt``, put that just as it reads
 on one line in the exclude file. Please note that beginning and trailing spaces
diff --git a/doc/faq.rst b/doc/faq.rst
index a235ea916..2dedb1033 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -101,7 +101,7 @@ Restic handles globbing and expansion in the following ways:
 -  Environment variables are not expanded in the file read via ``--files-from``
 -  ``*`` is expanded for paths read via ``--files-from``
 -  e.g. For backup sources given to restic as arguments on the shell, neither glob expansion nor shell variable replacement is done. If restic is called as ``restic backup '*' '$HOME'``, it will try to backup the literal file(s)/dir(s) ``*`` and ``$HOME``
--  Double-asterisk ``**`` only works in exclude patterns as this is a custom extension built into restic; the shell must not expand it
+-  Double-asterisk ``**`` matches across zero or more subdirectories in exclude patterns (e.g. ``foo/**/bar``). This is a custom extension beyond Go's ``filepath.Match``; make sure the shell does not expand it (e.g. by quoting the pattern). See :ref:`backup-excluding-files` for details
 
 
 How can I specify encryption passwords automatically?