Merge pull request #1708 from kabilar/download

Document options for the `dandi download --existing` flag

Author: yarikoptic

dandi/cli/cmd_download.py

@@ -64,9 +64,14 @@
     "--existing",
     type=click.Choice(list(DownloadExisting)),
     # TODO: verify-reupload (to become default)
-    help="What to do if a file found existing locally. 'refresh': verify "
-    "that according to the size and mtime, it is the same file, if not - "
-    "download and overwrite.",
+    help="How to handle paths that already exist locally. "
+    "For 'error', if the local file exists, display an error and skip downloading that asset. "
+    "For 'skip', if the local file exists, skip downloading that asset. "
+    "For 'overwrite', if the local file exists, overwrite that asset. "
+    "For 'overwrite-different', if the local file's hash is the same as on the server, the asset "
+    "is skipped; otherwise, it is redownloaded. "
+    "For 'refresh', if the local file's size and mtime are the same as on the server, the asset "
+    "is skipped; otherwise, it is redownloaded.",
     default="error",
     show_default=True,
 )

docs/source/cmdline/download.rst

@@ -20,6 +20,15 @@ Options
 
     How to handle paths that already exist locally  [default: ``error``]
 
+    For ``error``, if the local file exists, display an error and skip downloading that asset.
+
+    For ``skip``, if the local file exists, skip downloading that asset.
+
+    For ``overwrite``, if the local file exists, overwrite that asset.
+
+    For ``overwrite-different``, if the local file's hash is the same as on the
+    server, the asset is skipped; otherwise, it is redownloaded.
+
     For ``refresh``, if the local file's size and mtime are the same as on the
     server, the asset is skipped; otherwise, it is redownloaded.