docs/frontends/CLI.rst: clarification.

[tahoe-lafs/tahoe-lafs.git] / docs / frontends / CLI.rst

diff --git a/docs/frontends/CLI.rst b/docs/frontends/CLI.rst
index fa31dcf3f1a2a813cd1b74543e24f684f78f8be5..3a93cc86f0f8839fd7ec32374c39a721cc796f5b 100644 (file)
--- a/docs/frontends/CLI.rst
+++ b/docs/frontends/CLI.rst
@@ -203,8 +203,8 @@ The Tahoe-LAFS CLI commands use the same path syntax as ``scp`` and
 ``rsync`` -- an optional ``ALIAS:`` prefix, followed by the pathname or
 filename. Some commands (like "``tahoe cp``") use the lack of an alias to
 mean that you want to refer to a local file, instead of something from the
-Tahoe-LAFS filesystem. [TODO] Another way to indicate this is to start
-the pathname with a dot, slash, or tilde.
+Tahoe-LAFS filesystem. Another way to indicate this is to start the
+pathname with "./", "~/", "~username/", or "/".
 
 When you're dealing a single starting directory, the ``tahoe:`` alias is
 all you need. But when you want to refer to something that isn't yet
@@ -448,6 +448,28 @@ Command Examples
  This copies a file from your ``tahoe:`` root to a different directory, set up
  earlier with "``tahoe add-alias fun DIRCAP``" or "``tahoe create-alias fun``".
 
+ ``tahoe cp -r ~/my_dir/ tahoe:``
+
+ This copies the folder ``~/my_dir/`` and all its children to the grid, creating
+ the new folder ``tahoe:my_dir``. Note that the trailing slash is not required:
+ all source arguments which are directories will be copied into new
+ subdirectories of the target.
+
+ The behavior of ``tahoe cp``, like the regular UNIX ``/bin/cp``, is subtly
+ different depending upon the exact form of the arguments. In particular:
+
+* Trailing slashes indicate directories, but are not required.
+* If the target object does not already exist:
+  * and if the source is a single file, it will be copied into the target;
+  * otherwise, the target will be created as a directory.
+* If there are multiple sources, the target must be a directory.
+* If the target is a pre-existing file, the source must be a single file.
+* If the target is a directory, each source must be a named file, a named
+  directory, or an unnamed directory. It is not possible to copy an unnamed
+  file (e.g. a raw filecap) into a directory, as there is no way to know what
+  the new file should be named.
+
+
 ``tahoe unlink uploaded.txt``
 
 ``tahoe unlink tahoe:uploaded.txt``
@@ -476,7 +498,7 @@ Command Examples
 
 ``tahoe backup ~ work:backups``
 
- This command performs a full versioned backup of every file and directory
+ This command performs a versioned backup of every file and directory
  underneath your "``~``" home directory, placing an immutable timestamped
  snapshot in e.g. ``work:backups/Archives/2009-02-06_04:00:05Z/`` (note that
  the timestamp is in UTC, hence the "Z" suffix), and a link to the latest