From 908c506e3f0a2a9008892c80b4d5af51face3e68 Mon Sep 17 00:00:00 2001 From: Atemu Date: Fri, 20 Dec 2024 09:55:21 +0100 Subject: [PATCH] extract: document how to use wildcards in PATHs Fixes https://github.com/borgbackup/borg/issues/8589 --- docs/usage/extract.rst | 3 +++ src/borg/archiver.py | 12 ++++++++---- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/usage/extract.rst b/docs/usage/extract.rst index 292f84bdc..7fbab2923 100644 --- a/docs/usage/extract.rst +++ b/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 diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 31108ac0e..5232a988c 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -4371,11 +4371,15 @@ class Archiver: # 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