attempt to clarify move-vs-relink

This commit is contained in:
Zooko O'Whielacronx 2013-04-09 07:08:17 -06:00
parent 4751a46840
commit 389251860e

View File

@ -29,7 +29,7 @@ The Tahoe REST-ful Web API
6. `Attaching an Existing File Or Directory (by URI)`_
7. `Unlinking a Child`_
8. `Renaming a Child`_
9. `Moving a Child`_
9. `Relinking ("Moving") a Child`_
10. `Other Utilities`_
11. `Debugging and Testing Features`_
@ -1287,20 +1287,24 @@ Renaming a Child
for "False"; and the parameter is case-insensitive.
Moving a Child
--------------
Relinking ("Moving") a Child
----------------------------
``POST /uri/$DIRCAP/[SUBDIRS../]?t=relink&from_name=OLD&to_dir=$NEWDIRCAP/[NEWSUBDIRS../]&to_name=NEW``
``[&replace=true|false|only-files]`` (Tahoe >= v1.10)
This instructs the node to move a child of the given source directory,
into a different directory and/or to a different name. The command is
named ``relink`` because it works by adding a new link from the new
location, then removing the old link. The source and destination
directories must be writeable. If {{{to_dir}}} is not present, the child
link is renamed within the same directory. If {{{to_name}}} is not present
then it defaults to {{{from_name}}}. If the destination link (directory
and name) is the same as the source link, the operation has no effect.
This instructs the node to move a child of the given source directory, into
a different directory and/or to a different name. The command is named
``relink`` because what it does is add a new link to the child from the new
location, then remove the old link. Nothing is actually "moved" — the child
is still reachable through any path from which it was formerly reachable,
and the storage space occupied by its ciphertext is not affected.
The source and destination directories must be writeable. If {{{to_dir}}} is
not present, the child link is renamed within the same directory. If
{{{to_name}}} is not present then it defaults to {{{from_name}}}. If the
destination link (directory and name) is the same as the source link, the
operation has no effect.
Metadata from the source directory entry is preserved. Multiple levels of
descent in the source and destination paths are supported.