+.. -*- coding: utf-8-with-signature -*-
+
===========================
The Tahoe-LAFS CLI commands
===========================
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 ``'?'`` —
-before the program is able to read them, which may produce unexpected
-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 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, 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
``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
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``
``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
snapshot in work:backups/Latest/ . This command uses a small SQLite database
known as the "backupdb", stored in ``~/.tahoe/private/backupdb.sqlite``, to
remember which local files have been backed up already, and will avoid
- uploading files that have already been backed up. It compares timestamps and
- filesizes when making this comparison. It also re-uses existing directories
- which have identical contents. This lets it run faster and reduces the
- number of directories created.
+ uploading files that have already been backed up (except occasionally that
+ will randomly upload them again if it has been awhile since had last been
+ uploaded, just to make sure that the copy of it on the server is still good).
+ It compares timestamps and filesizes when making this comparison. It also
+ re-uses existing directories which have identical contents. This lets it
+ run faster and reduces the number of directories created.
If you reconfigure your client node to switch to a different grid, you
should delete the stale backupdb.sqlite file, to force "``tahoe backup``"
to upload all files to the new grid.
+ The fact that "tahoe backup" checks timestamps on your local files and
+ skips ones that don't appear to have been changed is one of the major
+ differences between "tahoe backup" and "tahoe cp -r". The other major
+ difference is that "tahoe backup" keeps links to all of the versions that
+ have been uploaded to the grid, so you can navigate among old versions
+ stored in the grid. In contrast, "tahoe cp -r" unlinks the previous
+ version from the grid directory and links the new version into place,
+ so unless you have a link to the older version stored somewhere else,
+ you'll never be able to get back to it.
+
``tahoe backup --exclude=*~ ~ work:backups``
Same as above, but this time the backup process will ignore any
projects / tahoe-lafs / tahoe-lafs.git / blobdiff