Improve 'tahoe put --help' to clarify behaviour for mutable files, and

[tahoe-lafs/tahoe-lafs.git] / src / allmydata / scripts / cli.py

diff --git a/src/allmydata/scripts/cli.py b/src/allmydata/scripts/cli.py
index 2a5f6611ddeb9008b903a8c7bd6a1bee6f028811..343a572807b3d7997167aa04199891e7e65dd4bb 100644 (file)
--- a/src/allmydata/scripts/cli.py
+++ b/src/allmydata/scripts/cli.py
@@ -1,4 +1,4 @@
-import os.path, re, sys, fnmatch
+import os.path, re, fnmatch
 from twisted.python import usage
 from allmydata.scripts.common import BaseOptions, get_aliases, get_default_nodedir, DEFAULT_ALIAS
 from allmydata.util.encodingutil import argv_to_unicode, argv_to_abspath, quote_output
@@ -50,9 +50,17 @@ class VDriveOptions(BaseOptions):
 
 
 class MakeDirectoryOptions(VDriveOptions):
+    optParameters = [
+        ("format", None, None, "Create a directory with the given format: SDMF or MDMF (case-insensitive)"),
+        ]
+
     def parseArgs(self, where=""):
         self.where = argv_to_unicode(where)
 
+        if self['format']:
+            if self['format'].upper() not in ("SDMF", "MDMF"):
+                raise usage.UsageError("%s is an invalid format" % self['format'])
+
     def getSynopsis(self):
         return "Usage:  %s mkdir [options] [REMOTE_DIR]" % (self.command_name,)
 
@@ -98,9 +106,14 @@ class ListOptions(VDriveOptions):
     def parseArgs(self, where=""):
         self.where = argv_to_unicode(where)
 
+    def getSynopsis(self):
+        return "Usage:  %s ls [options] [PATH]" % (self.command_name,)
+
     longdesc = """
     List the contents of some portion of the grid.
 
+    If PATH is omitted, "tahoe:" is assumed.
+
     When the -l or --long option is used, each line is shown in the
     following format:
 
@@ -162,7 +175,10 @@ Examples:
 
 class PutOptions(VDriveOptions):
     optFlags = [
-        ("mutable", "m", "Create a mutable file instead of an immutable one."),
+        ("mutable", "m", "Create a mutable file instead of an immutable one (like --format=SDMF)"),
+        ]
+    optParameters = [
+        ("format", None, None, "Create a file with the given format: SDMF and MDMF for mutable, CHK (default) for immutable. (case-insensitive)"),
         ]
 
     def parseArgs(self, arg1=None, arg2=None):
@@ -180,6 +196,10 @@ class PutOptions(VDriveOptions):
         if self.from_file == u"-":
             self.from_file = None
 
+        if self['format']:
+            if self['format'].upper() not in ("SDMF", "MDMF", "CHK"):
+                raise usage.UsageError("%s is an invalid format" % self['format'])
+
     def getSynopsis(self):
         return "Usage:  %s put [options] LOCAL_FILE REMOTE_FILE" % (self.command_name,)
 
@@ -188,7 +208,11 @@ class PutOptions(VDriveOptions):
     If REMOTE_FILE is missing, upload the file but do not link it into a
     directory; also print the new filecap to stdout. If LOCAL_FILE is missing
     or '-', data will be copied from stdin. REMOTE_FILE is assumed to start
-    with tahoe: unless otherwise specified."""
+    with tahoe: unless otherwise specified.
+
+    If the destination file already exists and is mutable, it will be modified
+    in-place, whether or not --mutable is specified. (--mutable only affects
+    creation of new files.)"""
 
     def getUsage(self, width=None):
         t = VDriveOptions.getUsage(self, width)
@@ -220,7 +244,7 @@ class CpOptions(VDriveOptions):
         self.destination = argv_to_unicode(args[-1])
 
     def getSynopsis(self):
-        return "Usage: tahoe cp [options] FROM.. TO"
+        return "Usage: %s cp [options] FROM.. TO" % (self.command_name,)
 
     longdesc = """
     Use 'tahoe cp' to copy files between a local filesystem and a Tahoe grid.
@@ -247,16 +271,16 @@ class CpOptions(VDriveOptions):
     slashes.
     """
 
-class RmOptions(VDriveOptions):
+class UnlinkOptions(VDriveOptions):
     def parseArgs(self, where):
         self.where = argv_to_unicode(where)
 
     def getSynopsis(self):
-        return "Usage:  %s rm [options] REMOTE_FILE" % (self.command_name,)
+        return "Usage:  %s unlink [options] REMOTE_FILE" % (self.command_name,)
 
-class UnlinkOptions(RmOptions):
+class RmOptions(UnlinkOptions):
     def getSynopsis(self):
-        return "Usage:  %s unlink [options] REMOTE_FILE" % (self.command_name,)
+        return "Usage:  %s rm [options] REMOTE_FILE" % (self.command_name,)
 
 class MvOptions(VDriveOptions):
     def parseArgs(self, frompath, topath):
@@ -470,8 +494,8 @@ subCommands = [
     ["get", None, GetOptions, "Retrieve a file from the grid."],
     ["put", None, PutOptions, "Upload a file into the grid."],
     ["cp", None, CpOptions, "Copy one or more files or directories."],
-    ["rm", None, RmOptions, "Unlink a file or directory on the grid."],
-    ["unlink", None, UnlinkOptions, "Unlink a file or directory on the grid (same as rm)."],
+    ["unlink", None, UnlinkOptions, "Unlink a file or directory on the grid."],
+    ["rm", None, RmOptions, "Unlink a file or directory on the grid (same as unlink)."],
     ["mv", None, MvOptions, "Move a file within the grid."],
     ["ln", None, LnOptions, "Make an additional link to an existing file or directory."],
     ["backup", None, BackupOptions, "Make target dir look like local dir."],
@@ -531,11 +555,14 @@ def cp(options):
     rc = tahoe_cp.copy(options)
     return rc
 
-def rm(options):
-    from allmydata.scripts import tahoe_rm
-    rc = tahoe_rm.rm(options)
+def unlink(options, command="unlink"):
+    from allmydata.scripts import tahoe_unlink
+    rc = tahoe_unlink.unlink(options, command=command)
     return rc
 
+def rm(options):
+    return unlink(options, command="rm")
+
 def mv(options):
     from allmydata.scripts import tahoe_mv
     rc = tahoe_mv.mv(options, mode="move")
@@ -585,8 +612,8 @@ dispatch = {
     "get": get,
     "put": put,
     "cp": cp,
+    "unlink": unlink,
     "rm": rm,
-    "unlink": rm,
     "mv": mv,
     "ln": ln,
     "backup": backup,