From b9fb74d2a09c43c7bac6fb733fda1fdb784e4fb7 Mon Sep 17 00:00:00 2001
From: Brian Warner <warner@lothar.com>
Date: Mon, 17 Jan 2011 00:14:21 -0800
Subject: [PATCH] Improve 'tahoe ln' help text. Patch by David-Sarah. Closes
 #1230.

---
 src/allmydata/scripts/cli.py   | 28 +++++++++++++++++++++++++---
 src/allmydata/test/test_cli.py |  3 ++-
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/src/allmydata/scripts/cli.py b/src/allmydata/scripts/cli.py
index b1da4159..8a3d4180 100644
--- a/src/allmydata/scripts/cli.py
+++ b/src/allmydata/scripts/cli.py
@@ -269,7 +269,29 @@ class LnOptions(VDriveOptions):
         self.to_file = argv_to_unicode(topath)
 
     def getSynopsis(self):
-        return "%s ln FROM TO" % (os.path.basename(sys.argv[0]),)
+        return "%s ln FROM_LINK TO_LINK" % (os.path.basename(sys.argv[0]),)
+
+    longdesc = """
+    Use 'tahoe ln' to duplicate a link (directory entry) already on the grid
+    to elsewhere on the grid. For example 'tahoe ln alias:some_file
+    alias:new_file'. causes 'alias:new_file' to point to the same object that
+    'alias:some_file' points to.
+
+    (The argument order is the same as Unix ln. To remember the order, you
+    can think of this command as copying a link, rather than copying a file
+    as 'tahoe cp' does. Then the argument order is consistent with that of
+    'tahoe cp'.)
+
+    When linking a remote file into a remote directory, you'll need to append
+    a '/' to the name of the remote directory, e.g. 'tahoe ln tahoe:file1
+    tahoe:dir/' (which is shorthand for 'tahoe ln tahoe:file1
+    tahoe:dir/file1'). If you forget the '/', e.g. 'tahoe ln tahoe:file1
+    tahoe:dir', the 'ln' command will refuse to overwrite the 'tahoe:dir'
+    directory, and will exit with an error.
+
+    Note that it is not possible to use this command to create links between
+    local and remote files.
+    """
 
 class BackupConfigurationError(Exception):
     pass
@@ -432,11 +454,11 @@ subCommands = [
     ["ls", None, ListOptions, "List a directory."],
     ["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."],
+    ["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)."],
     ["mv", None, MvOptions, "Move a file within the grid."],
-    ["ln", None, LnOptions, "Make an additional link to an existing file."],
+    ["ln", None, LnOptions, "Make an additional link to an existing file or directory."],
     ["backup", None, BackupOptions, "Make target dir look like local dir."],
     ["webopen", None, WebopenOptions, "Open a web browser to a grid file or directory."],
     ["manifest", None, ManifestOptions, "List all files/directories in a subtree."],
diff --git a/src/allmydata/test/test_cli.py b/src/allmydata/test/test_cli.py
index e56b8821..16a2ab9d 100644
--- a/src/allmydata/test/test_cli.py
+++ b/src/allmydata/test/test_cli.py
@@ -469,7 +469,8 @@ class Help(unittest.TestCase):
 
     def test_ln(self):
         help = str(cli.LnOptions())
-        self.failUnless("ln FROM TO" in help, help)
+        self.failUnless("ln FROM_LINK TO_LINK" in help, help)
+        self.failUnless("Use 'tahoe ln' to duplicate a link" in help)
 
     def test_backup(self):
         help = str(cli.BackupOptions())
-- 
2.45.2