Merge 854a7f822d into 1807d269cd

doc/040_backup.rst

@@ -339,6 +339,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.
@@ -369,6 +370,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

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?