better help / docs for borg extract --dry-run, fixes #1022

borg/archiver.py

@@ -1401,6 +1401,10 @@ class Archiver:
         be restricted by using the ``--exclude`` option.
 
         See the output of the "borg help patterns" command for more help on exclude patterns.
+
+        By using ``--dry-run``, you can do all extraction steps except actually writing the
+        output data: reading metadata and data chunks from the repo, checking the hash/hmac,
+        decrypting, decompressing.
         """)
         subparser = subparsers.add_parser('extract', parents=[common_parser], add_help=False,
                                           description=self.do_extract.__doc__,

docs/usage.rst

@@ -327,6 +327,9 @@ Examples
     # Extract entire archive and list files while processing
     $ borg extract -v --list /path/to/repo::my-files
 
+    # Verify whether an archive could be successfully extracted, but do not write files to disk
+    $ borg extract --dry-run /path/to/repo::my-files
+
     # Extract the "src" directory
     $ borg extract /path/to/repo::my-files home/USERNAME/src