@@ -4,38 +4,6 @@ weight = 7
44template = "doc.html"
55+++
66
7−# Contents
8−
9−- [Introduction](#introduction)
10−- [%warp](#warp) - Read and Subscribe.
11− - [%sing](#sing) - Read a file or directory.
12− - [%next](#next) - Subscribe for the next change to a file or directory.
13− - [%mult](#mult) - Subscribe for the next change to a set of files and/or directories.
14− - [%many](#many) - Track changes to a `desk` for the specified range of revisions.
15− - [Cancel Subscription](#cancel-subscription)
16−- [%info](#info) - Write and Modify.
17− - [%ins](#ins) - Add a file.
18− - [%del](#del) - Delete a file.
19− - [%mut](#mut) - Change a file.
20− - [Multiple Changes](#multiple-changes) - Change multiple files.
21−- [Manage Mounts](#manage-mounts)
22− - [%boat](#boat) - List mounts.
23− - [%mont](#mont) - Mount something.
24− - [%ogre](#ogre) - Unmount something.
25− - [%dirk](#dirk) - Commit changes.
26−- [Merge Desks](#merge-desks)
27− - [%merg](#merg)
28−- [Permissions](#permissions)
29− - [%perm](#perm) - Set file permissions.
30− - [%cred](#cred) - Add permission group.
31− - [%crew](#crew) - Get permission groups.
32− - [%crow](#crow) - Get group usage.
33−- [Foreign Ships](#foreign-ships)
34− - [%warp](#warp-remote) - Read a file on a foreign ship.
35− - [%merg](#merg-remote) - Merge from a foreign `desk`.
36−
37−# Introduction
38−
397This document contains a number of examples of interacting with Clay using its various `task`s. Sections correspond to the general details in the [API Reference](/docs/arvo/clay/tasks) document.
408
419Most examples will either use `|pass` to just send a `task` or the following thread to send a `task` and take the resulting `gift`. You can save the following thread to the `ted` directory of your `%home` `desk`:
@@ -61,11 +29,11 @@ Most examples will either use `|pass` to just send a `task` or the following thr
6129(pure:m !>(~))
6230```
6331
64−# `%warp`
32+## `%warp`
6533
6634See the [Read and Subscribe](/docs/arvo/clay/tasks#warp---read-and-track) section of the [API Reference](/docs/arvo/clay/tasks) document for general details.
6735
68−## `%sing`
36+### `%sing`
6937
7038Here we'll look at reading files by passing Clay a `%warp` `task` with a `%sing` `rave` and receiving a `%writ` `gift` containing the data in response.
7139
@@ -115,7 +83,7 @@ Here's a breakdown of the `task` we sent:
11583
11684
11785
118−## `%next`
86+### `%next`
11987
12088Here we'll look at subscribing to the next version of a file by passing Clay a `%warp` `task` with a `%next` `rave` and receiving a `%writ` `gift` when the file changes.
12189
@@ -151,7 +119,7 @@ Here's a breakdown of the task we sent:
151119
152120
153121
154−## `%mult`
122+### `%mult`
155123
156124Here we'll look at subscribing to the next version of multiple files by passing Clay a `%warp` `task` with a `%mult` `rave` and receiving a `%wris` `gift` when any of the files change.
157125
@@ -210,7 +178,7 @@ Here's a breakdown of the `task` we sent:
210178
211179
212180
213−## `%many`
181+### `%many`
214182
215183Here we'll look at subscribing to a range of changes to a `desk` by passing Clay a `%warp` `task` with a `%many` `rave` and receiving `%writ` `gift`s when changes occur.
216184
@@ -304,7 +272,7 @@ Here's a breakdown of the `task` we sent:
304272
305273
306274
307−## Cancel Subscription
275+### Cancel Subscription
308276
309277Here we'll look at cancelling a subscription by sending Clay a `%warp` `task` with a null `(unit rave)` in the `riff`.
310278
@@ -348,11 +316,11 @@ Here's a breakdown of the `task` we sent:
348316
349317
350318
351−# `%info`
319+## `%info`
352320
353321See the [Write and Modify](/docs/arvo/clay/tasks#write-and-modify) section of the [API Reference](/docs/arvo/clay/tasks) document for general details.
354322
355−## `%ins`
323+### `%ins`
356324
357325Here we'll look at adding a file by sending Clay a `%info` `task` containing a `%ins` `miso`.
358326
@@ -371,7 +339,7 @@ Here's a breakdown of the `task` we sent:
371339
372340
373341
374−## `%del`
342+### `%del`
375343
376344Here we'll look at deleting a file by sending Clay a `%info` `task` containing a `%del` `miso`.
377345
@@ -388,11 +356,11 @@ Here's a breakdown of the `task` we sent:
388356
389357
390358
391−## `%mut`
359+### `%mut`
392360
393361Identical to the [%ins](#ins) example, just replace `%ins` with `%mut`.
394362
395−## Multiple Changes
363+### Multiple Changes
396364
397365Here we'll look at changing multiple files in one request by sending Clay a `%info` `task` containing multiple `miso` in the `soba`.
398366
@@ -433,11 +401,11 @@ Save to `ted/multi-change.hoon`, `|commit %home`, and run:
433401- /~zod/home/38/baz/txt
434402```
435403
436−# Manage Mounts
404+## Manage Mounts
437405
438406See the [Manage Mounts](/docs/arvo/clay/tasks#manage-mounts) section of the [API Reference](/docs/arvo/clay/tasks) document for general details.
439407
440−## `%boat`
408+### `%boat`
441409
442410Here we'll look at requesting the list of existing mount points on a ship by sending Clay a `%boat` `task` and receiving a `%hill` `gift`.
443411
@@ -448,7 +416,7 @@ Using the `send-task-take-gift.hoon` thread, let's make such a request:
448416[%hill p=~[%home]]
449417```
450418
451−## `%mont`
419+### `%mont`
452420
453421Here we'll look at mounting `desk`s, directories and files to unix by sending Clay a `%mont` `task`.
454422
@@ -487,7 +455,7 @@ Let's try mounting a subdirectory and a single folder:
487455
488456If you look in your pier you'll now see a `gen` folder with the contents of `/gen` and a `hi.hoon` file by itself. Notice how the file extension has been automatically added.
489457
490−## `%ogre`
458+### `%ogre`
491459
492460Here we'll look at unmounting `desk`s, directories and files by sending Clay a `%ogre` `task`.
493461
@@ -518,7 +486,7 @@ If we specify a non-existent mount point it will fail with an error printed to t
518486
519487If we give it an unmounted `beam` it will not print an error but still won't work.
520488
521−## `%dirk`
489+### `%dirk`
522490
523491Here we'll look at committing changed files by sending Clay a `%dirk` `task`.
524492
@@ -535,11 +503,11 @@ Clay will print the changed files to the dojo with a leading `+`, `-` or `:` to
535503
536504If you have the same `desk` mounted to multiple points, a committed change in one mount will also update the others.
537505
538−# Merge Desks
506+## Merge Desks
539507
540508See the [Merge Desks](/docs/arvo/clay/tasks#merge-desks) section of the [API Reference](/docs/arvo/clay/tasks) document for general details.
541509
542−## `%merg`
510+### `%merg`
543511
544512Here we'll look at merging `desk`s by sending Clay a `%merg` `task` and receiving a `%mere` `gift` in response.
545513
@@ -610,11 +578,11 @@ Now change the text in the `foo.txt` in the `%home` `desk`, hit backspace to det
610578
611579You can also specify it by revision number or label.
612580
613−# Permissions
581+## Permissions
614582
615583See the [Permissions](/docs/arvo/clay/tasks#permissions) section of the [API Reference](/docs/arvo/clay/tasks) document for general details.
616584
617−## `%perm`
585+### `%perm`
618586
619587Here we'll look at setting permissions by sending Clay a `%perm` `task`.
620588
@@ -694,7 +662,7 @@ Here's a breakdown of a `%perm` task:
694662
695663
696664
697−## `%cred`
665+### `%cred`
698666
699667Here we'll look at creating a permission group by sending Clay a `%cred` `task`.
700668
@@ -706,7 +674,7 @@ Let's create a group called `'foo'` with a few ships:
706674
707675We'll check it with the next kind of `task`: [%crew](#crew).
708676
709−## `%crew`
677+### `%crew`
710678
711679Here we'll look at retrieving permission groups by sending Clay a `%crew` `task` and receiving a `%cruz` `gift` in response.
712680
@@ -717,7 +685,7 @@ Let's check, using the `send-task-take-gift.hoon` thread, for the permission gro
717685[%cruz cez={[p=~.foo q={~nec ~bud ~wes ~zod ~sev}]}]
718686```
719687
720−## `%crow`
688+### `%crow`
721689
722690Here we'll look at retrieving a list of all files and directories in all `desk`s which have permissions set for a group by sending Clay a `%crow` `task` and receiving a `%croz` `gift` in response.
723691
@@ -749,11 +717,11 @@ Now we'll use the `send-task-take-gift.hoon` thread to try `%crow`:
749717]
750718```
751719
752−# Foreign Ships
720+## Foreign Ships
753721
754722See the [Foreign Ships](/docs/arvo/clay/tasks#foreign-ships) section of the [API Reference](/docs/arvo/clay/tasks) document for general details.
755723
756−## `%warp` - Remote
724+### `%warp` - Remote
757725
758726Here we'll look at reading files on a foreign ship by sending Clay a `%warp` `task` with a foreign ship in the `wer` field and receiving a `%writ` `gift` in response.
759727
@@ -816,7 +784,7 @@ call: failed
816784/sys/vane/clay/hoon:<[1.365 48].[1.365 50]>
817785```
818786
819−## `%merg` - Remote
787+### `%merg` - Remote
820788
821789To merge a foreign `desk` into a local one, you just send Clay a `%merg` `task` (as you would for a local merge) and specify the foreign ship in the `her` field. For an example, see the [%merg](#merg) section.
822790