From 389251860ef0d499348c128d54c46ba35c142158 Mon Sep 17 00:00:00 2001 From: Zooko O'Whielacronx <zooko@zooko.com> Date: Tue, 9 Apr 2013 07:08:17 -0600 Subject: [PATCH] attempt to clarify move-vs-relink --- docs/frontends/webapi.rst | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) 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. -- 2.45.2