Merge pull request #8590 from Atemu/document-extract-wildcard

extract: document how to use wildcards in PATHs, fixes #8589

docs/usage/extract.rst

@@ -19,6 +19,9 @@ Examples
     # Extract the "src" directory but exclude object files
     $ borg extract my-files home/USERNAME/src --exclude '*.o'
 
+    # Extract only the C files
+    $ borg extract my-files 'sh:home/USERNAME/src/*.c'
+
     # Restore a raw device (must not be active/in use/mounted at that time)
     $ borg extract --stdout my-sdx | dd of=/dev/sdx bs=10M
 

src/borg/archiver/extract_cmd.py

@@ -127,11 +127,15 @@ class ExtractMixIn:
 
         extract_epilog = process_epilog(
             """
-        This command extracts the contents of an archive. By default, the entire
-        archive is extracted, but a subset of files and directories can be selected
-        by passing a list of ``PATH`` arguments. The file selection can be further
-        restricted by using the ``--exclude`` option.
+        This command extracts the contents of an archive.
 
+        By default, the entire archive is extracted, but a subset of files and directories
+        can be selected by passing a list of ``PATH`` arguments. The default interpretation
+        for the paths to extract is `pp:` which is a literal path-prefix match. If you want
+        to use e.g. a wildcard, you must select a different pattern style such as `sh:` or
+        `fm:`. See :ref:`borg_patterns` for more information.
+
+        The file selection can be further restricted by using the ``--exclude`` option.
         For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
 
         By using ``--dry-run``, you can do all extraction steps except actually writing the