The "``tahoe``" tool provides access to three categories of commands.
* node management: create a client/server node, start/stop/restart it
-* filesystem manipulation: list files, upload, download, delete, rename
+* filesystem manipulation: list files, upload, download, unlink, rename
* debugging: unpack cap-strings, examine share files
To get a list of all commands, just run "``tahoe``" with no additional
like Twisted, Foolscap, pycryptopp, and zfec. "``tahoe --version-and-path``"
will also show the path from which each library was imported.
-On Unix systems, the shell expands filename wildcards (``*`` and ``?``)
+On Unix systems, the shell expands filename wildcards (`` * and ? ``)
before the program is able to read them, which may produce unexpected
-results for many ``tahoe`` comands. We recommend that you avoid using them.
-On Windows, wildcards cannot be used to specify multiple filenames to
-``tahoe``.
+results for many ``tahoe`` comands. We recommend, if you use wildcards,
+to start the path with "``./``", for example "``tahoe cp -r ./* somewhere:``".
+This prevents the expanded filename from being interpreted as an option
+or as an alias, allowing filenames that start with a dash or contain
+colons to be handled correctly.
+
+On Windows, a single letter followed by a colon is treated as a drive
+specification rather than an alias (and is invalid unless a local path is
+allowed in that context). Wildcards cannot be used to specify multiple
+filenames to ``tahoe`` on Windows.
Unicode Support
---------------
creates a new directory and populates it with files that will allow the
"``tahoe start``" command to use it later on. This command creates nodes that
have client functionality (upload/download files), web API services
-(controlled by the 'webport' file), and storage services (unless
-``--no-storage`` is specified).
+(controlled by the '[node]web.port' configuration), and storage services
+(unless ``--no-storage`` is specified).
NODEDIR defaults to ``~/.tahoe/`` , and newly-created nodes default to
publishing a web server on port 3456 (limited to the loopback interface, at
=======================
These commands let you exmaine a Tahoe-LAFS filesystem, providing basic
-list/upload/download/delete/rename/mkdir functionality. They can be used as
+list/upload/download/unlink/rename/mkdir functionality. They can be used as
primitives by other scripts. Most of these commands are fairly thin wrappers
-around web-API calls, which are described in `<webapi.rst>`_.
+around web-API calls, which are described in `<webapi.rst>`__.
By default, all filesystem-manipulation commands look in ``~/.tahoe/`` to
figure out which Tahoe-LAFS node they should use. When the CLI command makes
Starting Directories
--------------------
-As described in `docs/architecture.rst <../architecture.rst>`_, the
+As described in `docs/architecture.rst <../architecture.rst>`__, the
Tahoe-LAFS distributed filesystem consists of a collection of directories
and files, each of which has a "read-cap" or a "write-cap" (also known as
a URI). Each directory is simply a table that maps a name to a child file
* ``DIRCAP/[SUBDIRS/]FILENAME`` or ``DIRCAP:./[SUBDIRS/]FILENAME`` for a path
relative to a directory cap.
+See `CLI Command Overview`_ above for information on using wildcards with
+local paths, and different treatment of colons between Unix and Windows.
+
+``FROMLOCAL`` or ``TOLOCAL`` is a path in the local filesystem.
+
Command Examples
----------------
Since Tahoe-LAFS v1.8.2, the alias name can be given with or without the
trailing colon.
+ On Windows, the alias should not be a single character, because it would be
+ confused with the drive letter of a local path.
+
``tahoe create-alias fun``
This combines "``tahoe mkdir``" and "``tahoe add-alias``" into a single step.
This uses the python 'webbrowser' module to cause a local web browser to
open to the web page for the given directory. This page offers interfaces to
- add, download, rename, and delete files in the directory. If no alias or
- path is given, this command opens the root directory of the default
- ``tahoe:`` alias.
+ add, download, rename, and unlink files and subdirectories in that directory.
+ If no alias or path is given, this command opens the root directory of the
+ default ``tahoe:`` alias.
``tahoe put file.txt``
``tahoe put file.txt --mutable``
- Create a new mutable file, fill it with the contents of ``file.txt``, and
- print the new write-cap to stdout.
+ Create a new (SDMF) mutable file, fill it with the contents of ``file.txt``,
+ and print the new write-cap to stdout.
``tahoe put file.txt MUTABLE-FILE-WRITECAP``
- Replace the contents of the given mutable file with the contents of ``file.txt``
- and prints the same write-cap to stdout.
+ Replace the contents of the given mutable file with the contents of
+ ``file.txt`` and print the same write-cap to stdout.
``tahoe cp file.txt tahoe:uploaded.txt``
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 rm uploaded.txt``
+``tahoe unlink uploaded.txt``
-``tahoe rm tahoe:uploaded.txt``
+``tahoe unlink tahoe:uploaded.txt``
- This deletes a file from your ``tahoe:`` root.
+ This unlinks a file from your ``tahoe:`` root (that is, causes there to no
+ longer be an entry ``uploaded.txt`` in the root directory that points to it).
+ Note that this does not delete the file from the grid.
+ For backward compatibility, ``tahoe rm`` is accepted as a synonym for
+ ``tahoe unlink``.
``tahoe mv uploaded.txt renamed.txt``
Same as above, but this time the backup process will ignore any
filename that will end with '~'. ``--exclude`` will accept any standard
Unix shell-style wildcards, as implemented by the
- `Python fnmatch module <http://docs.python.org/library/fnmatch.html>`_.
+ `Python fnmatch module <http://docs.python.org/library/fnmatch.html>`__.
You may give multiple ``--exclude`` options. Please pay attention that
the pattern will be matched against any level of the directory tree;
it's still impossible to specify absolute path exclusions.