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 950f6a79dff311f6fec5055a3bb61fcbc425e417..343a572807b3d7997167aa04199891e7e65dd4bb 100644 (file)
--- a/src/allmydata/scripts/cli.py
+++ b/src/allmydata/scripts/cli.py
@@ -51,14 +51,14 @@ class VDriveOptions(BaseOptions):
 
 class MakeDirectoryOptions(VDriveOptions):
     optParameters = [
-        ("format", None, None, "Create directory with the given format: SDMF and MDMF for mutable. (case-insensitive)"),
+        ("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", "CHK"):
+            if self['format'].upper() not in ("SDMF", "MDMF"):
                 raise usage.UsageError("%s is an invalid format" % self['format'])
 
     def getSynopsis(self):
@@ -106,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:
 
@@ -170,10 +175,10 @@ Examples:
 
 class PutOptions(VDriveOptions):
     optFlags = [
-        ("mutable", "m", "Create a mutable file instead of an immutable one. (DEPRECATED, use --format=SDMF)"),
+        ("mutable", "m", "Create a mutable file instead of an immutable one (like --format=SDMF)"),
         ]
     optParameters = [
-        ("format", None, None, "Create file with the given format: SDMF and MDMF for mutable, CHK (default) for immutable. (case-insensitive)"),
+        ("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):
@@ -203,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)