From 3e8d58767fa370a4c44bcb0057a191cd86db3778 Mon Sep 17 00:00:00 2001 From: Brian Warner Date: Mon, 2 Jun 2008 17:54:56 -0700 Subject: [PATCH] CLI: improve docs w.r.t. aliases, add examples to 'tahoe put' and 'tahoe get' help output. Addresses part of #431 --- docs/CLI.txt | 39 +++++++++++++++++++----------------- src/allmydata/scripts/cli.py | 32 +++++++++++++++++++++++++---- 2 files changed, 49 insertions(+), 22 deletions(-) diff --git a/docs/CLI.txt b/docs/CLI.txt index eab28bb4..fdc52d36 100644 --- a/docs/CLI.txt +++ b/docs/CLI.txt @@ -75,9 +75,6 @@ start using their changes. == Virtual Drive Manipulation == -[NOTE: This is a work-in-progress: none of this actually works yet]. - - These commands let you exmaine a Tahoe virtual drive, providing basic list/upload/download/delete/rename/mkdir functionality. They can be used as primitives by other scripts. Most of these commands are fairly thin wrappers @@ -91,9 +88,8 @@ a node on some other host, just create ~/.tahoe/ and copy that node's webapi URL into this file, and the CLI commands will contact that node instead of a local one. -These commands also use ~/.tahoe/private/root_dir.cap to figure out which -directory they ought to use a starting point. This is explained in more -detail below. +These commands also use a table of "aliases" to figure out which directory +they ought to use a starting point. This is explained in more detail below. === Root Directories === @@ -115,24 +111,31 @@ directory, but instead each user's personal filesystem has a root that they use as a starting point for all their operations. In fact, each tahoe node remembers a list of starting points, named -"aliases", in a file named ~/.tahoe/private/aliases . These are short strings -that stand for a directory read- or write- cap. The default starting point -uses an alias named "tahoe:", and for backwards compatibility can be stored -in a file named ~/.tahoe/private/root_dir.cap . - -The Tahoe CLI commands use the same filename syntax as scp and rsync, an +"aliases", in a file named ~/.tahoe/private/aliases . These aliases are short +strings that stand in for a directory read- or write- cap. The default +starting point uses an alias named "tahoe:". + +For backwards compatibility with Tahoe-1.0, if the "tahoe": alias is not +found in ~/.tahoe/private/aliases, the CLI will use the contents of +~/.tahoe/private/root_dir.cap instead. Tahoe-1.0 had only a single starting +point, and stored it in this root_dir.cap file, so Tahoe-1.1 will use it if +necessary. However, once you've set a "tahoe:" alias with "tahoe set-alias", +that will override anything in the old root_dir.cap file. + +The Tahoe CLI commands use the same filename syntax as scp and rsync: an optional "alias:" prefix, followed by the pathname or filename. Many commands have arguments which supply a default tahoe: alias if you don't provide one yourself, but it is always safe to supply the alias. 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 virtual filesystem. Another -way to indicate this is to start the pathname with a dot, slash, or tilde. +local file, instead of something from the tahoe virtual filesystem. [TODO] +Another way to indicate this is to start the pathname with a dot, slash, or +tilde. When you're dealing with your own personal filesystem, the "tahoe:" alias is -all you need. But when you want to refer to something that isn't yet in your -virtual drive, you need to refer to it by its URI. The way to do that is to -add an alias to it, with the "tahoe add-alias" command. Once you've added an -alias, you can use that alias as a prefix to the other commands. +all you need. But when you want to refer to something that isn't yet attached +to your virtual drive, you need to refer to it by its URI. The way to do that +is to add an alias to it, with the "tahoe add-alias" command. Once you've +added an alias, you can use that alias as a prefix to the other commands. The best way to get started with Tahoe is to create a node, start it, then use the following command to create a new directory and set it as your diff --git a/src/allmydata/scripts/cli.py b/src/allmydata/scripts/cli.py index 03014fc3..8e0b5fc6 100644 --- a/src/allmydata/scripts/cli.py +++ b/src/allmydata/scripts/cli.py @@ -11,8 +11,8 @@ class VDriveOptions(BaseOptions, usage.Options): "Look here to find out which Tahoe node should be used for all " "operations. The directory should either contain a full Tahoe node, " "or a file named node.url which points to some other Tahoe node. " - "It should also contain a file named root_dir.cap which contains " - "the root dirnode URI that should be used." + "It should also contain a file named private/aliases which contains " + "the mapping from alias name to root dirnode URI." ], ["node-url", "u", None, "URL of the tahoe node to use, a URL like \"http://127.0.0.1:8123\". " @@ -91,6 +91,17 @@ class GetOptions(VDriveOptions): local filesystem. If LOCAL_FILE is omitted or '-', the contents of the file will be written to stdout.""" + def getUsage(self, width=None): + t = VDriveOptions.getUsage(self, width) + t += """ +Examples: + % tahoe get FOO |less # write to stdout + % tahoe get tahoe:FOO |less # same + % tahoe get FOO bar # write to local file + % tahoe get tahoe:FOO bar # same +""" + return t + class PutOptions(VDriveOptions): optFlags = [ ("mutable", "m", "Create a mutable file instead of an immutable one."), @@ -119,8 +130,21 @@ class PutOptions(VDriveOptions): return "%s put LOCAL_FILE VDRIVE_FILE" % (os.path.basename(sys.argv[0]),) longdesc = """Put a file into the virtual drive (copying the file's - contents from the local filesystem). LOCAL_FILE is required to be a - local file (it can't be stdin).""" + contents from the local filesystem). If LOCAL_FILE is missing or '-', + data will be copied from stdin. VDRIVE_FILE is assumed to start with + tahoe: unless otherwise specified.""" + + def getUsage(self, width=None): + t = VDriveOptions.getUsage(self, width) + t += """ +Examples: + % cat FILE > tahoe put # create unlinked file from stdin + % cat FILE > tahoe put FOO # create tahoe:FOO from stdin + % cat FILE > tahoe put tahoe:FOO # same + % tahoe put bar FOO # copy local 'bar' to tahoe:FOO + % tahoe put bar tahoe:FOO # same +""" + return t class CpOptions(VDriveOptions): optFlags = [ -- 2.45.2