From: Brian Warner Date: Wed, 9 May 2012 23:46:53 +0000 (-0700) Subject: Improve webapi t=move docs. X-Git-Url: https://git.rkrishnan.org/provisioning?a=commitdiff_plain;h=2c5a7f7ba42212ab8da93e195b4e3dd626b33623;p=tahoe-lafs%2Ftahoe-lafs.git Improve webapi t=move docs. --- diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst index 11cee722..54b60b1a 100644 --- a/docs/frontends/webapi.rst +++ b/docs/frontends/webapi.rst @@ -1275,28 +1275,34 @@ Renaming A Child same child-cap under the new name, except that it preserves metadata. This operation cannot move the child to a different directory. - This operation will replace any existing child of the new name, making it - behave like the UNIX "``mv -f``" command. + By default, this operation will replace any existing child of the new name, + making it behave like the UNIX "``mv -f``" command. Adding a "replace=false" + argument causes the command to throw an HTTP 409 Conflict error if there is + already a child with the new name. Moving A Child ---------------- -``POST /uri/$DIRCAP/[SUBDIRS../]?t=move&from_name=OLD&to_dir=TARGET`` +``POST /uri/$DIRCAP/[SUBDIRS../]?t=move&from_name=OLD&to_dir=TARGETNAME[&target_type=name][&to_name=NEWNAME]`` +``POST /uri/$DIRCAP/[SUBDIRS../]?t=move&from_name=OLD&to_dir=TARGETURI&target_type=uri[&to_name=NEWNAME]`` This instructs the node to move a child of the given directory to a - different directory, both of which must be mutable. The child can also - be renamed in the process. The to_dir parameter should contain the name - of a subdirectory of the dircap from which the child is being moved - (multiple levels of descent are supported), unless the file is to be - moved to an unrelated directory. In the latter case, this can be - specified by passing a target_type=uri argument and the target URI in - to_dir=. If the target is the name of a subdirectory, this can be - signified by passing target_type=name. A new name for the child can - also be specified using the to_name= parameter. - - This operation will replace any existing child of the new name, making - it behave like the UNIX "``mv -f``" command. The original child is not - unlinked until it is linked into the target directory. + different directory, both of which must be mutable. If target_type=name + or is omitted, the to_dir= parameter should contain the name of a + subdirectory of the child's current parent directory (multiple levels of + descent are supported). If target_uri=, then to_dir= will be treated as + a dircap, allowing the child to be moved to an unrelated directory. + + The child can also be renamed in the process, by providing a new name in + the to_name= parameter. If omitted, the child will retain its existing + name. + + By default, this operation will replace any existing child of the new name, + making it behave like the UNIX "``mv -f``" command. Adding a "replace=false" + argument causes the command to throw an HTTP 409 Conflict error if there is + already a child with the new name. For safety, the child is not unlinked + from the old directory until its has been successfully added to the new + directory. Other Utilities ---------------