Merge pull request #9061 from ThomasWaldmann/document-extract-wildcard-1.4

extract: document how to use wildcards in PATHs

Author: ThomasWaldmann

docs/usage/extract.rst

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

src/borg/archiver.py

@@ -4371,11 +4371,15 @@ def diff_sort_spec_validator(s):
 
         # borg extract
         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 ``PATHs`` as arguments. The file selection can further
-        be 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