From: Zooko O'Whielacronx Date: Tue, 9 Apr 2013 13:08:17 +0000 (-0600) Subject: attempt to clarify move-vs-relink X-Git-Tag: allmydata-tahoe-1.10b1~19 X-Git-Url: https://git.rkrishnan.org/about.html?a=commitdiff_plain;h=refs%2Fpull%2F36%2Fhead;p=tahoe-lafs%2Ftahoe-lafs.git attempt to clarify move-vs-relink --- diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst index 433cd7a3..0f216130 100644 --- a/docs/frontends/webapi.rst +++ b/docs/frontends/webapi.rst @@ -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.