de4d0a2 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

Merge pull request #1180 from tinnus-napbus/update-clay-for-dist

de4d0a2tinnus-napbus5 years ago

content/docs/arvo/clay/architecture.md+32−33

compare with master

unifiedsplit

@@ -4,21 +4,20 @@ weight = 2

4template = "doc.html"

5+++

7−Clay is the primary filesystem for the [Arvo](/docs/arvo/overview) operating system,

7+Clay is the primary filesystem for the [Arvo](/docs/arvo/overview)

8−which is the [core](/docs/glossary/core/) of an urbit. The architecture of Clay is

8+operating system, which is the [core](/docs/glossary/core/) of an

9+urbit. The architecture of Clay is intrinsically connected with Arvo,

9−intrinsically connected with Arvo, but for this section we assume no knowledge of

10+but for this section we assume no knowledge of either Arvo or Urbit.

10−either Arvo or Urbit. We will point out only those features of

11+We will point out only those features of Arvo that are necessary for

11−Arvo that are necessary for an understanding of Clay, and we will

12−do so only when they arise.

12+an understanding of Clay, and we will do so only when they arise.

14The first relevant feature of Arvo is that it is a deterministic

15−system where input and output are defined as a series of events

15+system where input and output are defined as a series of events and

16−and effects. The state of Arvo is simply a pure function of its event

16+effects. The state of Arvo is simply a pure function of its event log.

17−log. None of the effects from an event are emitted until the

17+None of the effects from an event are emitted until the event is

18−event is entered in the log and persisted, either to disk or

18+entered in the log and persisted, either to disk or another trusted

19−another trusted source of persistence, such as a Kafka cluster.

19+source of persistence, such as a Kafka cluster. Consequently, Arvo is

20−Consequently, Arvo is a single-level store: everything in its

20+a single-level store: everything in its state is persistent.

21−state is persistent.

23In a more traditional OS, everything in RAM can be erased at any

22In a more traditional OS, everything in RAM can be erased at any

24time by power failure, and is always erased on reboot. Thus, a

23time by power failure, and is always erased on reboot. Thus, a

@@ -47,25 +46,25 @@ it supports typed data and is referentially transparent.

48### Revision Control

47### Revision Control

50−Every urbit has one or more `desk`s, which are independently

49+Every urbit has one or more desks, which are independently

51−revision-controlled branches. Each `desk` contains its own `mark`

50+revision-controlled branches. Each desk contains its own `mark`

52definitions, apps, and so forth.

51definitions, apps, and so forth.

54−Traditionally, an urbit has at least a `%home` `desk` and `%kids` `desk`. The

53+Traditionally, an Urbit ship has at least a `%base` desk, and usually

55−`%home` `desk` has all the system software from the distribution, along with your

54+`%garden` and `%landscape` desks. The `%base` desk has the kernel and

56−personal files. The `%home` `desk` is a fork of the `%kids` desk of whichever ship

55+base system software. The `%garden` desk has software pertaining to

56+the home screen. The `%landscape` desk contains software for the

57+Groups app. The `%base` desk is a fork of the `%base` desk of

57−you download [OTAs](/docs/glossary/ota-updates) from - typically your sponsor,

58+whichever ship you download system updates from - typically your

58−but theoretically may be any ship. You will also find references to a `%base`

59+sponsor, but theoretically may be any ship.

59−`desk` - which is not a real `desk`, rather it just a hash associated to the

60−`desk` from which your `%home` `desk` was forked.

62−A `desk` is a series of numbered commits, the most recent of which

61+A desk is a series of numbered commits, the most recent of which

63−represents the current state of the `desk`. A commit is composed of

62+represents the current state of the desk. A commit is composed of

64(1) an absolute time when it was created, (2) a list of zero or

63(1) an absolute time when it was created, (2) a list of zero or

65more parents, and (3) a map from paths to data.

64more parents, and (3) a map from paths to data.

67Most commits have exactly one parent, but the initial commit on a

66Most commits have exactly one parent, but the initial commit on a

68−`desk` may have zero parents, and merge commits have more than one

67+desk may have zero parents, and merge commits have more than one

69parent.

68parent.

71The non-metadata is stored as a `map` of `path`s to data. It's

70The non-metadata is stored as a `map` of `path`s to data. It's

@@ -88,10 +87,10 @@ only on the data within and not on whether or not it's stored

88directly, so we may on occasion rearrange the contents of the

87directly, so we may on occasion rearrange the contents of the

89blob store for performance reasons.

88blob store for performance reasons.

91−Recall that a `desk` is a series of numbered commits. Not every

90+Recall that a desk is a series of numbered commits. Not every

92−commit in a `desk` must be numbered. For example, if the base `desk`

91+commit in a desk must be numbered. For example, if the `%base` desk

93−has had 50 commits since home was forked from it, then a merge

92+has had 50 commits since `%foo` was forked from it, then a merge

94−from base to home will only add a single revision number to home,

93+from `%base` to `%foo` will only add a single revision number to home,

95although the full commit history will be accessible by traversing

94although the full commit history will be accessible by traversing

96the parentage of the individual commits.

95the parentage of the individual commits.

@@ -104,15 +103,15 @@ There are three ways to refer to particular commits in the

104revision history. Firstly, one can use the revision number.

103revision history. Firstly, one can use the revision number.

105Secondly, one can use any absolute time between the one numbered

104Secondly, one can use any absolute time between the one numbered

106commit and the next (inclusive of the first, exclusive of the

105commit and the next (inclusive of the first, exclusive of the

107−second). Thirdly, every `desk` has a `map` of labels to revision

106+second). Thirdly, every desk has a `map` of labels to revision

108numbers. These labels may be used to refer to specific commits.

107numbers. These labels may be used to refer to specific commits.

109

108

110Additionally, Clay is a global filesystem, so data on other urbits

109Additionally, Clay is a global filesystem, so data on other urbits

111is easily accessible the same way as data on our local urbit. In

110is easily accessible the same way as data on our local urbit. In

112−general, the path to a particular revision of a `desk` is

111+general, the path to a particular revision of a desk is

113`/~urbit-name/desk-name/revision`. Thus, to get `/try/readme/md`

112`/~urbit-name/desk-name/revision`. Thus, to get `/try/readme/md`

114−from revision 5 of the home `desk` on `~sampel-sipnym`, we refer to

113+from revision 5 of the `%base` desk on `~sampel-sipnym`, we refer to

115−`/~sampel-sipnym/home/5/try/readme/md`. Clay's namespace is thus

114+`/~sampel-sipnym/base/5/try/readme/md`. Clay's namespace is thus

116global and referentially transparent.

115global and referentially transparent.

117

116

118### A Typed Filesystem

117### A Typed Filesystem

content/docs/arvo/clay/data-types.md+2−9

@@ -68,7 +68,6 @@ to th pier) and `beam` is a domestic Clay directory.

69`pud` is an update that's waiting on a kernel upgrade.

71−

72#### `$room`, filesystem per domestic ship

71#### `$room`, filesystem per domestic ship

74```hoon

73```hoon

@@ -93,8 +92,7 @@ set of `desk`s on this ship, mapped to their `desk` state.

93+$ desk @tas

92+$ desk @tas

94```

93```

96−This is the name of a branch of the filesystem. The default `desk`s are `%home`

95+This is the name of a branch of the filesystem. The default `desk`s are `%base`, `%garden`, `%landscape`, `%webterm` and `%bitcoin`. Desks have

97−and `%kids`. More may be created by simply referencing them. `desk`s have

98independent histories and states, and they may be

96independent histories and states, and they may be

99[merged](/docs/arvo/clay/using#merging) into each other.

97[merged](/docs/arvo/clay/using#merging) into each other.

100

@@ -167,7 +165,6 @@ Like a `rave` but with provisions to store current versions for `%next` and `%ma

167Generally used when we store a request in our state somewhere. This is so that

165Generally used when we store a request in our state somewhere. This is so that

168we can determine whether new versions actually affect the path we're subscribed to.

166we can determine whether new versions actually affect the path we're subscribed to.

169

167

170−

171#### `$mood:clay`, single subscription request

168#### `$mood:clay`, single subscription request

172

169

173```hoon

170```hoon

@@ -194,7 +191,6 @@ any of its children.

194 +$ care ?(%a %b %c %d %e %f %p %r %s %t %u %v %w %x %y %z) :: clay submode

191 +$ care ?(%a %b %c %d %e %f %p %r %s %t %u %v %w %x %y %z) :: clay submode

195```

192```

196

193

197−

198This specifies what type of information is requested in a subscription

194This specifies what type of information is requested in a subscription

199or a scry.

195or a scry.

200

196

@@ -258,7 +254,6 @@ contents while `q.fil` is the data itself.

258this is empty. The keys are the names of the children and the values

254this is empty. The keys are the names of the children and the values

259are, recursively, the nodes themselves.

255are, recursively, the nodes themselves.

260

256

261−

262### `$arch`, shallow filesystem node

257### `$arch`, shallow filesystem node

263

258

264```hoon

259```hoon

@@ -275,6 +270,7 @@ those directories.

275The child directories are given by a `map` to null rather than a `set` so that the

270The child directories are given by a `map` to null rather than a `set` so that the

276ordering of the `map` will be the same as it is for an `axal`, allowing

271ordering of the `map` will be the same as it is for an `axal`, allowing

277efficient conversion for when the heavier node is needed.

272efficient conversion for when the heavier node is needed.

273+

278```hoon

274```hoon

279++ axal

275++ axal

280 |$ [item]

276 |$ [item]

@@ -400,7 +396,6 @@ is all the subscribers from our ship to the foreign `desk`.

400`regs` are `(map path rule)`, and so `per` is a `map` of read permissions by

396`regs` are `(map path rule)`, and so `per` is a `map` of read permissions by

401`path` and `pew` is a `map` of write permissions by `path`.

397`path` and `pew` is a `map` of write permissions by `path`.

402

398

403−

404#### `$rind`, foreign request manager

399#### `$rind`, foreign request manager

405

400

406```hoon

401```hoon

@@ -547,7 +542,6 @@ blob, and `r` is the delta.

547`%direct` is the case where we simply have the data directly. `q` is the data.

542`%direct` is the case where we simply have the data directly. `q` is the data.

548These almost always come from the creation of a file.

543These almost always come from the creation of a file.

549

544

550−

551#### `+urge`, list change

545#### `+urge`, list change

552

546

553```hoon

547```hoon

@@ -685,4 +679,3 @@ commit itself.

685revision number, whichever is smaller.

679revision number, whichever is smaller.

686

680

687`lar` is the set of new commits, and `bar` is the set of new content.

681`lar` is the set of new commits, and `bar` is the set of new content.

688−

content/docs/arvo/clay/examples.md+99−102

@@ -6,7 +6,7 @@ template = "doc.html"

7This 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.

9−Most 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`:

9+Most 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 the `%base` `desk` on a fake ship:

11`send-task-take-gift.hoon`

@@ -40,7 +40,7 @@ Here we'll look at reading files by passing Clay a `%warp` `task` with a `%sing`

40Using the `send-task-take-gift.hoon` thread, let's try reading `gen/hood/hi.hoon`:

42```

43−> -send-task-take-gift [%warp our %home ~ %sing %x da+now /gen/hood/hi/hoon]

43+> -send-task-take-gift [%warp our %base ~ %sing %x da+now /gen/hood/hi/hoon]

44```

46You should see something like this as the output:

@@ -49,7 +49,7 @@ You should see something like this as the output:

49[ %writ

50 p

51 [ ~

52− [ p=[p=%x q=[%da p=~2021.5.20..23.37.50..e79b] r=%home]

52+ [ p=[p=%x q=[%da p=~2021.5.20..23.37.50..e79b] r=%base]

53 q=/gen/hood/hi/hoon

54 r

55 [ p=%hoon

@@ -67,11 +67,11 @@ You should see something like this as the output:

67The `cage` in the `riot` of the `%writ` contains the file's data due to our use of an `%x` `care`. It needn't be `%x` though. If we change it to `%u`, for example, we'll get a `?` `cage` instead:

69```

70−> -send-task-take-gift [%warp our %home ~ %sing %x da+now /gen/hood/hi/hoon]

70+> -send-task-take-gift [%warp our %base ~ %sing %x da+now /gen/hood/hi/hoon]

71[ %writ

72 p

73 [ ~

74− [ p=[p=%u q=[%da p=~2021.5.20..23.42.21..bb33] r=%home]

74+ [ p=[p=%u q=[%da p=~2021.5.20..23.42.21..bb33] r=%base]

75 q=/gen/hood/hi/hoon

76 r=[p=%flag q=[#t/?(%.y %.n) q=0]]

77 ]

@@ -90,27 +90,27 @@ Here we'll look at subscribing to the next version of a file by passing Clay a `

90Using the `send-task-take-gift.hoon` thread, let's subscribe to the next version of `foo.txt`:

92```

93−> -send-task-take-gift [%warp our %home ~ %next %x da+now /foo/txt]

93+> -send-task-take-gift [%warp our %base ~ %next %x da+now /foo/txt]

94```

96−Now, in unix, create a file called `foo.txt` in the root of the `home` directory of your ship. In the dojo, hit backspace to disconnect the thread from the dojo prompt and run `|commit %home`. You should see something like:

96+Now, in unix, create a file called `foo.txt` in the root of the `base` directory of your ship. In the dojo, hit backspace to disconnect the thread from the dojo prompt and run `|commit %base`. You should see something like:

98```

99−> |commit %home

99+> |commit %base

100>=

101−[%writ p=[~ [p=[p=%x q=[%ud p=3] r=%home] q=/foo/txt r=[p=%txt q=[#t/*'' q=0]]]]]

101+[%writ p=[~ [p=[p=%x q=[%ud p=3] r=%base] q=/foo/txt r=[p=%txt q=[#t/*'' q=0]]]]]

102−+ /~zod/home/3/foo/txt

102++ /~zod/base/3/foo/txt

103```

104

105As you can see, the `riot` in the `%writ` includes a `cage` with the data of `/foo/txt` due to our use of an `%x` `care`.

106

107−Now run the thread again, and this time delete the file in unix and again `|commit %home` in the dojo. You should see:

107+Now run the thread again, and this time delete the file in unix and again `|commit %base` in the dojo. You should see:

108

109```

110−> |commit %home

110+> |commit %base

111>=

112[%writ p=~]

113−- /~zod/home/4/foo/txt

113+- /~zod/base/4/foo/txt

114```

115

116You can see the `riot` is just `~` due to the file being deleted.

@@ -141,7 +141,7 @@ This thread will subscribe to `/foo/txt` with an `%x` `care` and `/bar/txt` with

141 [%u /bar/txt]

142 ==

143;< =bowl:strand bind:m get-bowl:strandio

144−=/ =task:clay [%warp our.bowl %home ~ %mult da+now.bowl files]

144+=/ =task:clay [%warp our.bowl %base ~ %mult da+now.bowl files]

145=/ =card:agent:gall [%pass /mult %arvo %c task]

146;< ~ bind:m (send-raw-card:strandio card)

147;< response=(pair wire sign-arvo) bind:m take-sign-arvo:strandio

@@ -149,27 +149,27 @@ This thread will subscribe to `/foo/txt` with an `%x` `care` and `/bar/txt` with

149(pure:m !>(~))

150```

151

152−Save the above to `ted/sub-mult.hoon`, `|commit %home` and run with `-sub-mult`. Now, create `foo.txt` and `bar.txt` in your home directory, hit backspace in the dojo to disconnect the thread and run `|commit %home`. You should see something like:

152+Save the above to `ted/sub-mult.hoon`, `|commit %base` and run with `-sub-mult`. Now, create `foo.txt` and `bar.txt` in your base directory, hit backspace in the dojo to disconnect the thread and run `|commit %base`. You should see something like:

153

154```

155−> |commit %home

155+> |commit %base

156>=

157[%wris p=[%da p=~2021.4.27..06.07.08..5ec4] q={[p=%u q=/bar/txt] [p=%x q=/foo/txt]}]

158−+ /~zod/home/151/foo/txt

158++ /~zod/base/151/foo/txt

159−+ /~zod/home/151/bar/txt

159++ /~zod/base/151/bar/txt

160```

161

162You'll notice that, unlike a `%writ`, the `%wris` doesn't give you the data. It merely tells you the `care`s and `path`s of the files that changed. If you need to actually get the data, you can just scry or send a request for the files in question.

163

164−Now, run the thread again, open `bar.txt` in an editor, modify its contents, save it and `|commit %home`. You'll notice you didn't receive a `%wris`. This is because we subscribed to `/bar/txt` with `%u` care and its existence didn't change.

164+Now, run the thread again, open `bar.txt` in an editor, modify its contents, save it and `|commit %base`. You'll notice you didn't receive a `%wris`. This is because we subscribed to `/bar/txt` with `%u` care and its existence didn't change.

165

166−Lastly, delete `foo.txt` and `|commit %home`. You should see something like:

166+Lastly, delete `foo.txt` and `|commit %base`. You should see something like:

167

168```

169−> |commit %home

169+> |commit %base

170>=

171[%wris p=[%da p=~2021.4.27..06.15.03..0da4] q={[p=%x q=/foo/txt]}]

172−- /~zod/home/153/foo/txt

172+- /~zod/base/153/foo/txt

173```

174

175As you can see, a relevant change to any of the subscribed files will trigger a response, not just when all of them change.

@@ -182,7 +182,7 @@ Here's a breakdown of the `task` we sent:

182

183Here 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.

184

185−This thread will subscribe to changes to your `%home` `desk` for the next three minutes. The `track` is `%.y` so it will only inform you of changes, not send the full `nako`. It will only get updates if the specified file exists. It contains a `main-loop` that will take an arbitrary number of `sign`s and print them out in the dojo. Since it never ends, you'll need to stop it with the `:spider|kill` command in the dojo.

185+This thread will subscribe to changes to your `%base` `desk` for the next three minutes. The `track` is `%.y` so it will only inform you of changes, not send the full `nako`. It will only get updates if the specified file exists. It contains a `main-loop` that will take an arbitrary number of `sign`s and print them out in the dojo. Since it never ends, you'll need to stop it with the `:spider|kill` command in the dojo.

186

187`sub-many.hoon`

188

@@ -213,30 +213,30 @@ This thread will subscribe to changes to your `%home` `desk` for the next three

213 (strand-fail:strand %no-arg ~)

214=/ =path u.uarg

215;< =bowl:strand bind:m get-bowl:strandio

216−=/ =task:clay [%warp our.bowl %home ~ %many %.y da+now.bowl da+(add ~m3 now.bowl) path]

216+=/ =task:clay [%warp our.bowl %base ~ %many %.y da+now.bowl da+(add ~m3 now.bowl) path]

217=/ =card:agent:gall [%pass /many %arvo %c task]

218;< ~ bind:m (send-raw-card:strandio card)

219;< ~ bind:m take-sign-loop

220(pure:m !>(~))

221```

222

223−Make sure `foo.txt` doesn't exist in the root of your `%home` `desk`. Save this to `ted/sub-many.hoon`, `|commit %home`, run it like `-sub-many /foo/txt`, and hit backspace in the dojo to free up the dojo prompt. Now, add a file called `bar.txt` to your `desk` and `|commit %home`. You should see something like:

223+Make sure `foo.txt` doesn't exist in the root of your `%base` `desk`. Save this to `ted/sub-many.hoon`, `|commit %base`, run it like `-sub-many /foo/txt`, and hit backspace in the dojo to free up the dojo prompt. Now, add a file called `bar.txt` to your `desk` and `|commit %base`. You should see something like:

224

225```

226−> |commit %home

226+> |commit %base

227>=

228−+ /~zod/home/260/bar/txt

228++ /~zod/base/260/bar/txt

229```

230

231−Notice you've received no `%writ` from Clay. This is because `/foo/txt` doesn't exist. Now, create `foo.txt` and `|commit %home` again. You should see:

231+Notice you've received no `%writ` from Clay. This is because `/foo/txt` doesn't exist. Now, create `foo.txt` and `|commit %base` again. You should see:

232

233```

234−> |commit %home

234+> |commit %base

235>=

236[ p=/many

237− q=[%clay [%writ p=[~ [p=[p=%w q=[%ud p=261] r=%home] q=/ r=[p=%null q=[#t/@n q=0]]]]]]

237+ q=[%clay [%writ p=[~ [p=[p=%w q=[%ud p=261] r=%base] q=/ r=[p=%null q=[#t/@n q=0]]]]]]

238]

239−+ /~zod/home/261/foo/txt

239++ /~zod/base/261/foo/txt

240```

241

242Now that `/foo/txt` exists it will inform you of updates. Note that if you delete `/foo/txt` again it will again stop sending updates.

@@ -244,24 +244,24 @@ Now that `/foo/txt` exists it will inform you of updates. Note that if you delet

244Now try adding `baz.txt`:

245

246```

247−> |commit %home

247+> |commit %base

248>=

249[ p=/many

250− q=[%clay [%writ p=[~ [p=[p=%w q=[%ud p=262] r=%home] q=/ r=[p=%null q=[#t/@n q=0]]]]]]

250+ q=[%clay [%writ p=[~ [p=[p=%w q=[%ud p=262] r=%base] q=/ r=[p=%null q=[#t/@n q=0]]]]]]

251]

252−+ /~zod/home/262/baz/txt

252++ /~zod/base/262/baz/txt

253```

254

255Now wait until the three minutes is up and try making a change, for example deleting `baz.txt`:

256

257```

258−> |commit %home

258+> |commit %base

259>=

260[ p=/many

261− q=[%clay [%writ p=[~ [p=[p=%w q=[%ud p=264] r=%home] q=/ r=[p=%null q=[#t/@n q=0]]]]]]

261+ q=[%clay [%writ p=[~ [p=[p=%w q=[%ud p=264] r=%base] q=/ r=[p=%null q=[#t/@n q=0]]]]]]

262]

263[p=/many q=[%clay [%writ p=~]]]

264−- /~zod/home/263/baz/txt

264+- /~zod/base/263/baz/txt

265```

266

267You can see that along with the normal `%writ` it's also sent a second `%writ` with a null `riot` to indicate the subscription has ended. This is because it has now passed the end of the range of `case`s to which you subscribed.

@@ -289,10 +289,10 @@ This thread will subscribe to the `%next` version of `/foo/txt`, then immediatel

289=/ m (strand ,vase)

290^- form:m

291;< =bowl:strand bind:m get-bowl:strandio

292−=/ =task:clay [%warp our.bowl %home ~ %next %x da+now.bowl /foo/txt]

292+=/ =task:clay [%warp our.bowl %base ~ %next %x da+now.bowl /foo/txt]

293=/ =card:agent:gall [%pass /next %arvo %c task]

294;< ~ bind:m (send-raw-card:strandio card)

295−=. task [%warp our.bowl %home ~]

295+=. task [%warp our.bowl %base ~]

296=. card [%pass /next %arvo %c task]

297;< ~ bind:m (send-raw-card:strandio card)

298;< =riot:clay bind:m (take-writ:strandio /next)

@@ -300,12 +300,12 @@ This thread will subscribe to the `%next` version of `/foo/txt`, then immediatel

300(pure:m !>(~))

301```

302

303−Save the above to `ted/stop-sub.hoon`, `|commit %home`, run it with `-stop-sub` and hit backspace to detach it from the dojo prompt. Now, add `foo.txt` to the root of your `%home` `desk` and `|commit %home`. You should see:

303+Save the above to `ted/stop-sub.hoon`, `|commit %base`, run it with `-stop-sub` and hit backspace to detach it from the dojo prompt. Now, add `foo.txt` to the root of your `%base` `desk` and `|commit %base`. You should see:

304

305```

306−> |commit %home

306+> |commit %base

307>=

308−+ /~zod/home/266/foo/txt

308++ /~zod/base/266/foo/txt

309```

310

311As you can see we've received no `%writ`. We can thus conclude the subscription has successfully been cancelled.

@@ -327,11 +327,11 @@ Here we'll look at adding a file by sending Clay a `%info` `task` containing a `

327Let's try adding a `foo.txt` file with 'foo' as its contents:

328

329```

330−> |pass [%c [%info %home %& [/foo/txt %ins %txt !>(~['foo'])]~]]

330+> |pass [%c [%info %base %& [/foo/txt %ins %txt !>(~['foo'])]~]]

331−+ /~zod/home/5/foo/txt

331++ /~zod/base/5/foo/txt

332```

333

334−If you have a look in the home of your pier you'll see there's now a file called `foo.txt` with the text `foo` in it.

334+If you have a look in the base of your pier you'll see there's now a file called `foo.txt` with the text `foo` in it.

335

336We've created the `cage` of the content like `[%txt !>(~['foo'])]`, if you want to write something besides a text file you'd just give it the appropriate `mark` and `vase`.

337

@@ -346,11 +346,11 @@ Here we'll look at deleting a file by sending Clay a `%info` `task` containing a

346Let's try deleting the `foo.txt` file created in the [previous example](#ins):

347

348```

349−> |pass [%c [%info %home %& [/foo/txt %del ~]~]]

349+> |pass [%c [%info %base %& [/foo/txt %del ~]~]]

350−- /~zod/home/6/foo/txt

350+- /~zod/base/6/foo/txt

351```

352

353−If you have a look in the home of your pier you'll see the `foo.txt` file is now gone.

353+If you have a look in the base of your pier you'll see the `foo.txt` file is now gone.

354

355Here's a breakdown of the `task` we sent:

356

@@ -384,21 +384,21 @@ Since `soba` is just a `list` of `miso`, you can add a bunch of `miso` and they'

384 [/bar/txt %del ~]

385 [/baz/txt %del ~]

386 ==

387−;< ~ bind:m (send-raw-card:strandio [%pass /info %arvo %c %info %home %& soba-a])

387+;< ~ bind:m (send-raw-card:strandio [%pass /info %arvo %c %info %base %& soba-a])

388−;< ~ bind:m (send-raw-card:strandio [%pass /info %arvo %c %info %home %& soba-b])

388+;< ~ bind:m (send-raw-card:strandio [%pass /info %arvo %c %info %base %& soba-b])

389(pure:m !>(~))

390```

391

392−Save to `ted/multi-change.hoon`, `|commit %home`, and run:

392+Save to `ted/multi-change.hoon`, `|commit %base`, and run:

393

394```

395> -multi-change

396−+ /~zod/home/37/foo/txt

396++ /~zod/base/37/foo/txt

397−+ /~zod/home/37/bar/txt

397++ /~zod/base/37/bar/txt

398−+ /~zod/home/37/baz/txt

398++ /~zod/base/37/baz/txt

399−- /~zod/home/38/foo/txt

399+- /~zod/base/38/foo/txt

400−- /~zod/home/38/bar/txt

400+- /~zod/base/38/bar/txt

401−- /~zod/home/38/baz/txt

401+- /~zod/base/38/baz/txt

402```

403

404## Manage Mounts

@@ -413,44 +413,41 @@ Using the `send-task-take-gift.hoon` thread, let's make such a request:

413

414```

415> -send-task-take-gift [%boat ~]

416−[%hill p=~[%home]]

416+[%hill p=~[%base]]

417```

418

419### `%mont`

420

421Here we'll look at mounting `desk`s, directories and files to unix by sending Clay a `%mont` `task`.

422

423−Let's first try mounting our `%kids` desk:

423+Let's first try mounting our `%garden` desk:

424

425```

426−> |pass [%c [%mont %kids [our %kids da+now] /]]

426+> |pass [%c [%mont %garden [our %garden da+now] /]]

427```

428

429−If you look in your pier, you should now see a `kids` folder which contains the contents of that `desk`.

429+If you look in your pier, you should now see a `garden` folder which contains the contents of that `desk`.

430

431If we make a `%boat` request as detailed in the [%boat](#boat) section, we'll now see the mount point listed:

432

433```

434> -send-task-take-gift [%boat ~]

435−[%hill p=~[%kids %home]]cruz gift. It looks like:

435+[%hill p=~[%garden %base]]

436−

437−[%cruz cez=(map @ta crew)] :: permission groups

438−The cez is just a map from group name to crew

439```

436```

440

437

441Note the mount point doesn't need to match a `desk`, file or directory. We can also do:

438Note the mount point doesn't need to match a `desk`, file or directory. We can also do:

442

439

443```

440```

444−> |pass [%c [%mont %wibbly-wobbly [our %home da+now] /]]

441+> |pass [%c [%mont %wibbly-wobbly [our %base da+now] /]]

445```

442```

446

443

447−And you'll now see that there's a `wibbly-wobbly` folder with the contents of the `%home` `desk`. You'll also notice we can mount the same file or directory more than once. There's no problem having `%home` mounted to both `home` and `wibbly-wobbly`. The only requirement is that their mount points be unique.

444+And you'll now see that there's a `wibbly-wobbly` folder with the contents of the `%base` `desk`. You'll also notice we can mount the same file or directory more than once. There's no problem having `%base` mounted to both `base` and `wibbly-wobbly`. The only requirement is that their mount points be unique.

448

445

449Let's try mounting a subdirectory and a single folder:

446Let's try mounting a subdirectory and a single folder:

450

447

451```

448```

452−> |pass [%c [%mont %gen [our %home da+now] /gen]]

449+> |pass [%c [%mont %gen [our %base da+now] /gen]]

453−> |pass [%c [%mont %hi [our %home da+now] /gen/hood/hi]]

450+> |pass [%c [%mont %hi [our %base da+now] /gen/hood/hi]]

454```

451```

455

452

456If 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.

453If 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.

@@ -459,10 +456,10 @@ If you look in your pier you'll now see a `gen` folder with the contents of `/ge

459

456

460Here we'll look at unmounting `desk`s, directories and files by sending Clay a `%ogre` `task`.

457Here we'll look at unmounting `desk`s, directories and files by sending Clay a `%ogre` `task`.

461

458

462−Let's unmount what we mounted in the [%mont](#mont) section. First we'll unmount the `%kids` desk:

459+Let's unmount what we mounted in the [%mont](#mont) section. First we'll unmount the `%garden` desk:

463

460

464```

461```

465−|pass [%c [%ogre %kids]]

462+|pass [%c [%ogre %garden]]

466```

463```

467

464

468Our custom mount point `%wibbly-wobbly`:

465Our custom mount point `%wibbly-wobbly`:

@@ -480,8 +477,8 @@ And the single `hi.hoon` we previously mounted by specifying its mount point `%h

480If we specify a non-existent mount point it will fail with an error printed to the dojo like:

477If we specify a non-existent mount point it will fail with an error printed to the dojo like:

481

478

482```

479```

483−> |pass [%c [%ogre %kids]]

480+> |pass [%c [%ogre %foo]]

484−[%not-mounted %kids]

481+[%not-mounted %foo]

485```

482```

486

483

487If we give it an unmounted `beam` it will not print an error but still won't work.

484If we give it an unmounted `beam` it will not print an error but still won't work.

@@ -492,11 +489,11 @@ Here we'll look at committing changed files by sending Clay a `%dirk` `task`.

492

489

493This `task` performs the same function as the `|commit` dojo command.

490This `task` performs the same function as the `|commit` dojo command.

494

491

495−With your `%home` `desk` mounted, try adding a file and send a `%dirk` to commit the change:

492+With your `%base` `desk` mounted, try adding a file and send a `%dirk` to commit the change:

496

493

497```

494```

498−> |pass [%c [%dirk %home]]

495+> |pass [%c [%dirk %base]]

499−+ /~zod/home/12/foo/txt

496++ /~zod/base/12/foo/txt

500```

497```

501

498

502Clay will print the changed files to the dojo with a leading `+`, `-` or `:` to indicate a new file, deleted file and changed file respectively.

499Clay will print the changed files to the dojo with a leading `+`, `-` or `:` to indicate a new file, deleted file and changed file respectively.

@@ -514,7 +511,7 @@ Here we'll look at merging `desk`s by sending Clay a `%merg` `task` and receivin

514First, using the `send-task-take-gift.hoon` thread, let's try creating a new `desk`:

511First, using the `send-task-take-gift.hoon` thread, let's try creating a new `desk`:

515

512

516```

513```

517−> -send-task-take-gift [%merg %foo our %home da+now %init]

514+> -send-task-take-gift [%merg %foo our %base da+now %init]

518[%mere p=[%.y p={}]]

515[%mere p=[%.y p={}]]

519```

516```

520

517

@@ -522,15 +519,15 @@ Now if we scry for our `desk`s we'll see `%foo` is there:

522

519

523```

520```

524> .^((set desk) %cd /===)

521> .^((set desk) %cd /===)

525−{%home %foo %kids}

522+{%bitcoin %base %landscape %webterm %garden %foo}

526```

523```

527

524

528Next, we'll create a merge conflict and try a couple of things. Mount `%foo` with `|mount /=foo=`, then add a `foo.txt` to both `desk`s but with different text in each and `|commit` them.

525Next, we'll create a merge conflict and try a couple of things. Mount `%foo` with `|mount /=foo=`, then add a `foo.txt` to both `desk`s but with different text in each and `|commit` them.

529

526

530−Now we'll try merging `%home` into `%foo` with a `%mate` strategy:

527+Now we'll try merging `%base` into `%foo` with a `%mate` strategy:

531

528

532```

529```

533−> -send-task-take-gift [%merg %foo our %home da+now %mate]

530+> -send-task-take-gift [%merg %foo our %base da+now %mate]

534[ /foo

531[ /foo

535 [ %clay

532 [ %clay

536 [ %mere

533 [ %mere

@@ -549,14 +546,14 @@ Now we'll try merging `%home` into `%foo` with a `%mate` strategy:

549As you can see, the merge has failed. Let's try again with a `%meld` strategy:

546As you can see, the merge has failed. Let's try again with a `%meld` strategy:

550

547

551```

548```

552−> -send-task-take-gift [%merg %foo our %home da+now %meld]

549+> -send-task-take-gift [%merg %foo our %base da+now %meld]

553[/foo [%clay [%mere p=[%.y p={/foo/txt}]]]]

550[/foo [%clay [%mere p=[%.y p={/foo/txt}]]]]

554```

551```

555

552

556Now the merge has succeeded and the `%mere` notes the file with a merge conflict. If we try with a `%only-that` strategy:

553Now the merge has succeeded and the `%mere` notes the file with a merge conflict. If we try with a `%only-that` strategy:

557

554

558```

555```

559−> -send-task-take-gift [%merg %foo our %home da+now %only-that]

556+> -send-task-take-gift [%merg %foo our %base da+now %only-that]

560[/foo [%clay [%mere p=[%.y p={}]]]]

557[/foo [%clay [%mere p=[%.y p={}]]]]

561: /~zod/foo/6/foo/txt

558: /~zod/foo/6/foo/txt

562```

559```

@@ -566,10 +563,10 @@ Now the merge has succeeded and the `%mere` notes the file with a merge conflict

566Next, let's look at subscribing for future changes. Since the `case` is specified explicitly in the `%merge` `task`, we can set it in the future:

563Next, let's look at subscribing for future changes. Since the `case` is specified explicitly in the `%merge` `task`, we can set it in the future:

567

564

568```

565```

569−> -send-task-take-gift [%merg %foo our %home da+(add ~m2 now) %only-that]

566+> -send-task-take-gift [%merg %foo our %base da+(add ~m2 now) %only-that]

570```

567```

571

568

572−Now change the text in the `foo.txt` in the `%home` `desk`, hit backspace to detach the thread and `|commit %home`. After the two minutes pass you should see:

569+Now change the text in the `foo.txt` in the `%base` `desk`, hit backspace to detach the thread and `|commit %base`. After the two minutes pass you should see:

573

570

574```

571```

575[/foo [%clay [%mere p=[%.y p={}]]]]

572[/foo [%clay [%mere p=[%.y p={}]]]]

@@ -589,7 +586,7 @@ Here we'll look at setting permissions by sending Clay a `%perm` `task`.

589First, let's allow `~nes` to read `/gen/hood/hi/hoon`:

586First, let's allow `~nes` to read `/gen/hood/hi/hoon`:

590

587

591```

588```

592−> |pass [%c [%perm %home /gen/hood/hi/hoon %r ~ %white (sy [%.y ~nes]~)]]

589+> |pass [%c [%perm %base /gen/hood/hi/hoon %r ~ %white (sy [%.y ~nes]~)]]

593```

590```

594

591

595...and we'll do a `%p` scry to see that the permission was set:

592...and we'll do a `%p` scry to see that the permission was set:

@@ -602,7 +599,7 @@ First, let's allow `~nes` to read `/gen/hood/hi/hoon`:

602You can see that `~nes` is now in the read whitelist. Next, let's try a write permission:

599You can see that `~nes` is now in the read whitelist. Next, let's try a write permission:

603

600

604```

601```

605−> |pass [%c [%perm %home /ted %w ~ %white (sy [%.y ~nes]~)]]

602+> |pass [%c [%perm %base /ted %w ~ %white (sy [%.y ~nes]~)]]

606```

603```

607

604

608You can see `~nes` can now write to `/ted`:

605You can see `~nes` can now write to `/ted`:

@@ -624,7 +621,7 @@ Since we've set it for the whole `/ted` directory, if we check a file inside it

624Now let's try setting both read and write permissions:

621Now let's try setting both read and write permissions:

625

622

626```

623```

627−> |pass [%c [%perm %home /gen/help/hoon %rw `[%black (sy [%.y ~nes]~)] `[%white (sy [%.y ~nes]~)]]]

624+> |pass [%c [%perm %base /gen/help/hoon %rw `[%black (sy [%.y ~nes]~)] `[%white (sy [%.y ~nes]~)]]]

628```

625```

629

626

630```

627```

@@ -637,7 +634,7 @@ Lastly, let's look at deleting a permission rule we've previously set. To do tha

637For example, to remove a read permission (or write if you specify `%w`):

634For example, to remove a read permission (or write if you specify `%w`):

638

635

639```

636```

640−> |pass [%c [%perm %home /gen/help/hoon %r ~]]

637+> |pass [%c [%perm %base /gen/help/hoon %r ~]]

641```

638```

642

639

643```

640```

@@ -648,7 +645,7 @@ For example, to remove a read permission (or write if you specify `%w`):

648...and to remove both read and write at the same time:

645...and to remove both read and write at the same time:

649

646

650```

647```

651−> |pass [%c [%perm %home /gen/help/hoon %rw ~ ~]]

648+> |pass [%c [%perm %base /gen/help/hoon %rw ~ ~]]

652```

649```

653

650

654```

651```

@@ -692,8 +689,8 @@ Here we'll look at retrieving a list of all files and directories in all `desk`s

692First we'll set a couple of permissions for the `foo` group we created in the [%cred](#cred) section:

689First we'll set a couple of permissions for the `foo` group we created in the [%cred](#cred) section:

693

690

694```

691```

695−> |pass [%c [%perm %home /gen/hood/hi/hoon %w ~ %white (sy [%.n 'foo']~)]]

692+> |pass [%c [%perm %base /gen/hood/hi/hoon %w ~ %white (sy [%.n 'foo']~)]]

696−> |pass [%c [%perm %home /ted %w ~ %white (sy [%.n 'foo']~)]]

693+> |pass [%c [%perm %base /ted %w ~ %white (sy [%.n 'foo']~)]]

697```

694```

698

695

699Notice we use a `%.n` in the `whom` to indicate a group rather than the `%.y` of a ship.

696Notice we use a `%.n` in the `whom` to indicate a group rather than the `%.y` of a ship.

@@ -704,7 +701,7 @@ Now we'll use the `send-task-take-gift.hoon` thread to try `%crow`:

704> -send-task-take-gift [%crow 'foo']

701> -send-task-take-gift [%crow 'foo']

705[ %croz

702[ %croz

706 rus

703 rus

707− { [ p=%home

704+ { [ p=%base

708 q

705 q

709 [ r={}

706 [ r={}

710 w

707 w

@@ -725,29 +722,29 @@ See the [Foreign Ships](/docs/arvo/clay/tasks#foreign-ships) section of the [API

725

722

726Here 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.

723Here 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.

727

724

728−We'll use a fake ~nes as the the foreign ship and a fake ~zod as the local ship.

725+We'll use a fake `~nes` as the the foreign ship and a fake `~zod` as the local ship.

729

726

730−First we'll set permissions on the foreign ship. Create a file called `foo.txt` in the `%home` of ~nes, then send a `%perm` request to allow ~zod to read and write the file:

727+First we'll set permissions on the foreign ship. Create a file called `foo.txt` in the `%base` of ~nes, then send a `%perm` request to allow ~zod to read and write the file:

731

728

732```

729```

733−> |pass [%c [%perm %home /foo/txt %rw `[%white (sy [%.y ~zod]~)] `[%white (sy [%.y ~zod]~)]]]

730+> |pass [%c [%perm %base /foo/txt %rw `[%white (sy [%.y ~zod]~)] `[%white (sy [%.y ~zod]~)]]]

734```

731```

735

732

736−If we scry the file for its permissions with a `%p` `care`, we'll see ~zod is now whitelisted:

733+If we scry the file for its permissions with a `%p` `care`, we'll see `~zod` is now whitelisted:

737

734

738```

735```

739> .^([r=dict:clay w=dict:clay] %cp /===/foo/txt)

736> .^([r=dict:clay w=dict:clay] %cp /===/foo/txt)

740[r=[src=/foo/txt rul=[mod=%white who=[p={~zod} q={}]]] w=[src=/foo/txt rul=[mod=%white who=[p={~zod} q={}]]]]

737[r=[src=/foo/txt rul=[mod=%white who=[p={~zod} q={}]]] w=[src=/foo/txt rul=[mod=%white who=[p={~zod} q={}]]]]

741```

738```

742

739

743−Back on ~zod: Using the `send-task-take-gift.hoon` thread, send a `%x` read request for `/foo/txt` on ~nes like:

740+Back on `~zod`: Using the `send-task-take-gift.hoon` thread, send a `%x` read request for `/foo/txt` on ~nes like:

744

741

745```

742```

746−> -send-task-take-gift [%warp ~nes %home ~ %sing %x da+now /foo/txt]

743+> -send-task-take-gift [%warp ~nes %base ~ %sing %x da+now /foo/txt]

747[ %writ

744[ %writ

748 p

745 p

749 [ ~

746 [ ~

750− [ p=[p=%x q=[%da p=~2021.5.3..08.24.22..9ce7] r=%home]

747+ [ p=[p=%x q=[%da p=~2021.5.3..08.24.22..9ce7] r=%base]

751 q=/foo/txt

748 q=/foo/txt

752 r=[p=%txt q=[#t/txt=*'' q=[7.303.014 0]]]

749 r=[p=%txt q=[#t/txt=*'' q=[7.303.014 0]]]

753 ]

750 ]

@@ -758,11 +755,11 @@ Back on ~zod: Using the `send-task-take-gift.hoon` thread, send a `%x` read requ

758As you can see, we've received a `%writ` containing the requested data just as we would with a local request. Let's try a `%u`:

755As you can see, we've received a `%writ` containing the requested data just as we would with a local request. Let's try a `%u`:

759

756

760```

757```

761−> -send-task-take-gift [%warp ~nes %home ~ %sing %u da+now /foo/txt]

758+> -send-task-take-gift [%warp ~nes %base ~ %sing %u da+now /foo/txt]

762[ %writ

759[ %writ

763 p

760 p

764 [ ~

761 [ ~

765− [ p=[p=%u q=[%da p=~2021.5.3..08.26.32..88cf] r=%home]

762+ [ p=[p=%u q=[%da p=~2021.5.3..08.26.32..88cf] r=%base]

766 q=/foo/txt

763 q=/foo/txt

767 r=[p=%flag q=[#t/?(%.y %.n) q=0]]

764 r=[p=%flag q=[#t/?(%.y %.n) q=0]]

768 ]

765 ]

@@ -773,7 +770,7 @@ As you can see, we've received a `%writ` containing the requested data just as w

773If we send a `%d` request however, it will crash:

770If we send a `%d` request however, it will crash:

774

771

775```

772```

776−> -send-task-take-gift [%warp ~nes %home ~ %sing %d da+now /foo/txt]

773+> -send-task-take-gift [%warp ~nes %base ~ %sing %d da+now /foo/txt]

777call: failed

774call: failed

778/sys/vane/clay/hoon:<[4.085 3].[4.314 5]>

775/sys/vane/clay/hoon:<[4.085 3].[4.314 5]>

779...

776...

content/docs/arvo/clay/scry.md+6−6

@@ -8,7 +8,7 @@ The various Clay scries are specified by a `care`, which is a single character c

9```

10> /===

11−[~.~zod ~.home ~.~2021.4.26..02.29.03..d31b ~]

11+[~.~zod ~.base ~.~2021.4.26..02.29.03..d31b ~]

12```

14## %a - Build hoon.

@@ -51,7 +51,7 @@ Example:

52```

53> .^((set desk) %cd /===)

54−{%home %kids}

54+{%bitcoin %base %landscape %webterm %garden}

55```

57## %e - Static mark core.

@@ -213,12 +213,12 @@ This will return the most recent revision number of a `desk` that has been fully

213Example:

214

215```

216−> .^(=cass:clay %cs /(scot %p (sein:title our now our))/kids/1/late)

216+> .^(=cass:clay %cs /(scot %p (sein:title our now our))/base/1/late)

217cass=[ud=50 da=~2021.4.22..10.38.50..57a8]

218```

219

220```

221−> .^(=cass:clay %cs /~sampel/kids/1/late)

221+> .^(=cass:clay %cs /~sampel/base/1/late)

222cass=[ud=0 da=~2000.1.1]

223```

224

@@ -229,12 +229,12 @@ This will return the mergebase (i.e. most recent common ancestor) between two `d

229Examples:

230

231```

232−> .^((list tako:clay) %cs /===/base/(scot %p (sein:title our now our))/kids)

232+> .^((list tako:clay) %cs /===/base/(scot %p (sein:title our now our))/base)

233~[102.787.244.596.033.419.950.995.540.301.493.841.569.518.772.322.508.085.465.561.801.703.148.627.263.473]

234```

235

236```

237−> .^((list tako:clay) %cs /===/base/~sampel/kids)

237+> .^((list tako:clay) %cs /===/base/~sampel/base)

238~

239```

240

content/docs/arvo/clay/tasks.md+2−2

@@ -108,7 +108,7 @@ This subscribes to all changes to a `desk` for the specified range of `case`s. N

108If the `track` is `%.y` it will just return a `%writ` like:

109

110```hoon

111−[%writ p=[~ [p=[p=%w q=[%ud p=256] r=%home] q=/ r=[p=%null q=[#t/@n q=0]]]]]

111+[%writ p=[~ [p=[p=%w q=[%ud p=256] r=%base] q=/ r=[p=%null q=[#t/@n q=0]]]]]

112```

113

114...that merely informs you of a change. If you want the actual data you'll have to request it separately.

@@ -494,7 +494,7 @@ Note that if you're reading a whole `desk` or directory, all subfolders and file

494

495To 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 details on making such requests, see the [Merge Desks](#merge-desks) section.

496

497−The foreign ship will respond only if correct permissions have been set. See the [Permissions](#permissions) section for details. By default, a ship's `%kids` desk is set to be publicly readable, so unless permissions have been manually modified, you should be able to merge from any `%kids` `desk`.

497+The foreign ship will respond only if correct permissions have been set. See the [Permissions](#permissions) section for details.

498

499Note that all subfolders and individual files within the `desk` must permit your reading in order for the merge to succeed. If even one file does not permit you reading it, the remote ship will not respond to the request at all.

500

content/docs/arvo/clay/using.md+67−61

@@ -6,50 +6,51 @@ template = "doc.html"

7### Reading and Subscribing

9−When reading from Clay, there are three types of requests. A

9+When reading from Clay, there are three types of requests. A

10−`%sing` request asks for data at single revsion. A `%next`

10+`%sing` request asks for data at single revsion. A `%next`

11request asks to be notified the next time there's a change to

12−given file. A `%many` request asks to be notified on every

12+given file. A `%many` request asks to be notified on every

13change in a `desk` for a range of changes.

15For `%sing` and `%next`, there are generally three things to be

16−queried. A `%u` request simply checks for the existence of a

16+queried. A `%u` request simply checks for the existence of a

17−file at a path. A `%x` request gets the data in the file at a

17+file at a path. A `%x` request gets the data in the file at a

18−path. A `%y` request gets a hash of the data in the file at the

18+path. A `%y` request gets a hash of the data in the file at the

19−path combined with all its children and their data. Thus, `%y`

19+path combined with all its children and their data. Thus, `%y`

20of a node changes if it or any of its children change.

22−A `%sing` request is fulfilled immediately if possible. If the

22+A `%sing` request is fulfilled immediately if possible. If the

23requested revision is in the future, or is on another ship for

24which we don't have the result cached, we don't respond

25−immediately. If the requested revision is in the future, we wait

25+immediately. If the requested revision is in the future, we wait

26−until the revision happens before we respond to the request. If

26+until the revision happens before we respond to the request. If

27the request is for data on another ship, we pass on the request

28−to the other ship. In general, Clay subscriptions, like most

28+to the other ship. In general, Clay subscriptions, like most

29things in Urbit, aren't guaranteed to return immediately.

30They'll return when they can, and they'll do so in a

31referentially transparent manner.

33A `%next` request checks the query at the given revision, and it

34produces the result of the query the next time it changes, along

35−with the revision number when it changes. Thus, a `%next` of a

35+with the revision number when it changes. Thus, a `%next` of a

36`%u` is triggered when a file is added or deleted, a `%next` of a

37`%x` is triggered when a file is added, deleted, or changed, and

38a `%next` of a `%y` is triggered when a file or any of its

39children is added, deleted, or changed.

41A `%many` request is triggered every time the given `desk` has a

42−new revision. Unlike a `%next`, a `%many` has both a start and

42+new revision. Unlike a `%next`, a `%many` has both a start and

43−an end revision, after which it stops returning. For `%next`, a

43+an end revision, after which it stops returning. For `%next`, a

44single change is reported, and if the caller wishes to hear of

45−the next change, it must resubscribe. For `%many`, every revision

45+the next change, it must resubscribe. For `%many`, every revision

46−from the start to the end triggers a response. Since a `%many`

46+from the start to the end triggers a response. Since a `%many`

47request doesn't ask for any particular data, there aren't `%u`,

48`%x`, and `%y` versions for it.

50### Unix sync

52Usage:

53+

53```

54```

54|mount %/path/to/directory %mount-point

55|mount %/path/to/directory %mount-point

55|commit %mount-point

56|commit %mount-point

@@ -76,123 +77,128 @@ be automatically committed with `|autocommit %mount-point`.

76### Merging

77### Merging

78Usage:

79Usage:

80+

79```

81```

80|merge %target-desk ~source-ship %source-desk

82|merge %target-desk ~source-ship %source-desk

81|merge %target-desk ~source-ship %source-desk, =gem %strategy

83|merge %target-desk ~source-ship %source-desk, =gem %strategy

82|merge %target-desk ~source-ship %source-desk, =cas ud+5

84|merge %target-desk ~source-ship %source-desk, =cas ud+5

83```

85```

85−Clay supports various merge strategies. A "commit" is a snapshot of

87+Clay supports various merge strategies. A "commit" is a snapshot of

86−the files with a list of parents plus a date. Most commits have

88+the files with a list of parents plus a date. Most commits have

87−one parent; a "merge" commit is a commit with two parents. The

89+one parent; a "merge" commit is a commit with two parents. The

88−%home `desk` starts with an initial commit with no parents; commits

90+`%base` `desk` starts with an initial commit with no parents; commits

89with several parents ("octopus merges") are possible but we don't

91with several parents ("octopus merges") are possible but we don't

90generate them right now.

92generate them right now.

91−

93+

92Unless otherwise specified, all of the following create a new commit

94Unless otherwise specified, all of the following create a new commit

93with the source and destination commits as parents.

95with the source and destination commits as parents.

94−

96+

95−Several strategies need a "merge-base". They find it by identifying

97+Several strategies need a "merge-base". They find it by identifying

96−the most recent common ancestor of the two `desk`s. If none, fail

98+the most recent common ancestor of the two `desk`s. If none, fail

97with `%merge-no-merge-base`; if there are two or more, pick one.

99with `%merge-no-merge-base`; if there are two or more, pick one.

100

99#### Strategies

101#### Strategies

100−

102+

101−**`%init`**: the only way to create a `desk`. Not a true merge, since it

103+**`%init`**: the only way to create a `desk`. Not a true merge, since it

102simply assigns the source commit to the destination.

104simply assigns the source commit to the destination.

103−

105+

104**`%fine`**: if source or destination are in the ancestry of each other,

106**`%fine`**: if source or destination are in the ancestry of each other,

105−use the newer one; else abort. If the destination is ahead of the

107+use the newer one; else abort. If the destination is ahead of the

106−source, succeed but do nothing. If the source is ahead of the

108+source, succeed but do nothing. If the source is ahead of the

107destination, assign the next revision number to the source commit.

109destination, assign the next revision number to the source commit.

108Some call this "fast-forward".

110Some call this "fast-forward".

109−

111+

110**`%meet`**: combine changes, failing if both sides changed the same file.

112**`%meet`**: combine changes, failing if both sides changed the same file.

111Specifically, take diff(merge-base,source) and

113Specifically, take diff(merge-base,source) and

112diff(merge-base,destination) and combine them as long as those diffs

114diff(merge-base,destination) and combine them as long as those diffs

113touch different files.

115touch different files.

114−

116+

115**`%mate`**: combine changes, failing if both sides changed the same part

117**`%mate`**: combine changes, failing if both sides changed the same part

116−of a file. Identical to `%meet`, except that some marks, like `%hoon`,

118+of a file. Identical to `%meet`, except that some marks, like `%hoon`,

117allow intelligent merge of changes to different parts of a file.

119allow intelligent merge of changes to different parts of a file.

118−

120+

119**`%meld`**: combine changes; if both sides changed the same part of a

121**`%meld`**: combine changes; if both sides changed the same part of a

120file, use the version of the file in the merge-base.

122file, use the version of the file in the merge-base.

121−

123+

122**`%only-this`**: create a merge commit with exactly the contents of the

124**`%only-this`**: create a merge commit with exactly the contents of the

123destination `desk`.

125destination `desk`.

124−

126+

125**`%only-that`**: create a merge commit with exactly the contents of the

127**`%only-that`**: create a merge commit with exactly the contents of the

126source commit.

128source commit.

127−

129+

128**`%take-this`**: create a merge commit with exactly the contents of the

130**`%take-this`**: create a merge commit with exactly the contents of the

129destination `desk` except take any files from the source commit which

131destination `desk` except take any files from the source commit which

130are not in the destination `desk`.

132are not in the destination `desk`.

131−

133+

132**`%take-that`**: create a merge commit with exactly the contents of the

134**`%take-that`**: create a merge commit with exactly the contents of the

133source commit except preserve any files from the destination `desk`

135source commit except preserve any files from the destination `desk`

134which are not in the source commit.

136which are not in the source commit.

135−

137+

136**`%meet-this`**: merge as in `%meet`, except if both sides changed the same

138**`%meet-this`**: merge as in `%meet`, except if both sides changed the same

137file, use the version in the destination `desk`.

139file, use the version in the destination `desk`.

138−

140+

139**`%meet-that`**: merge as in `%meet`, except if both sides changed the same

141**`%meet-that`**: merge as in `%meet`, except if both sides changed the same

140file, use the version in the source commit.

142file, use the version in the source commit.

141−

143+

142#### Examples and notes:

144#### Examples and notes:

143−

145+

144The most common merge strategy is `%mate`, which is a normal 3-way

146The most common merge strategy is `%mate`, which is a normal 3-way

145merge which aborts on conflict.

147merge which aborts on conflict.

146−

148+

147−`%take-that` is useful to "force" an OTA. After running `%take-that`,

149+`%take-that` is useful to "force" an OTA. After running `%take-that`,

148you're guaranteed to have exactly the files in the source commit plus

150you're guaranteed to have exactly the files in the source commit plus

149any files you separately added.

151any files you separately added.

150−

152+

151−We speak of merging into a destination *`desk`* from a source *commit*

153+We speak of merging into a destination _`desk`_ from a source _commit_

152because while you can only merge on top of a `desk`, you can merge from

154because while you can only merge on top of a `desk`, you can merge from

153−historical commits. For example,

155+historical commits. For example,

156+

154−```

157+```

155−|merge %old our %home, =cas ud+5, =gem %init

158+|merge %old our %base, =cas ud+5, =gem %init

156```

159```

160+

157−will create a new `desk` called `%old` with the 5th commit in `%home`.

161+will create a new `desk` called `%old` with the 5th commit in `%base`.

158You can revert the contents of a `desk` to what they were yesterday

162You can revert the contents of a `desk` to what they were yesterday

159with

163with

164+

160```

165```

161−|merge %home our %home, =cas da+(sub now ~d1), =gem %only-that

166+|merge %base our %base, =cas da+(sub now ~d1), =gem %only-that

162```

167```

163−

168+

164Note this is a normal `%only-that merge`, which means you're creating a

169Note this is a normal `%only-that merge`, which means you're creating a

165−*new* commit with the old *contents*.

170+_new_ commit with the old _contents_.

166−

171+

167`%meld` is rarely used on its own, however if you specify `%auto` or

172`%meld` is rarely used on its own, however if you specify `%auto` or

168omit the merge strategy, `%kiln` will run a `%meld` merge into a scratch

173omit the merge strategy, `%kiln` will run a `%meld` merge into a scratch

169`desk` and then annotate the conflicts there.

174`desk` and then annotate the conflicts there.

170−

175+

171If you resolve merge conflicts manually, for example by mounting the

176If you resolve merge conflicts manually, for example by mounting the

172`desk`s, copying the files in Unix and then running `|commit`, you

177`desk`s, copying the files in Unix and then running `|commit`, you

173−should usually run an `%only-this merge`. This will not change the

178+should usually run an `%only-this merge`. This will not change the

174newly-fixed contents of your `desk`, but it will record that the merge

179newly-fixed contents of your `desk`, but it will record that the merge

175happened so that those conflicts don't reappear in later merges.

180happened so that those conflicts don't reappear in later merges.

176−

181+

177If you get a `%merge-no-merge-base` error, this means you're trying to

182If you get a `%merge-no-merge-base` error, this means you're trying to

178−merge two `desk`s which have no common ancestors. You need to give

183+merge two `desk`s which have no common ancestors. You need to give

179them a common ancestor by choosing a merge strategy which doesn't

184them a common ancestor by choosing a merge strategy which doesn't

180need a merge-base, like `%only-this`, `%only-that`, `%take-this`, or

185need a merge-base, like `%only-this`, `%only-that`, `%take-this`, or

181`%take-that`.

186`%take-that`.

182−

187+

183`%take-this` could be useful to install 3rd party software, but you

188`%take-this` could be useful to install 3rd party software, but you

184couldn't get subsequent updates this way, since the files would

189couldn't get subsequent updates this way, since the files would

185−already exist in the destination `desk`. Something like "take only

190+already exist in the destination `desk`. Something like "take only

186the files which aren't in my OTA source or any other 3rd party app"

191the files which aren't in my OTA source or any other 3rd party app"

187−would be basically correct. This would require a parameter listing

192+would be basically correct. This would require a parameter listing

188the `desk`s to not conflict with.

193the `desk`s to not conflict with.

189−

194+

190`%meet-this` and `%meet-that` imply the existence of `%mate-this` and

195`%meet-this` and `%meet-that` imply the existence of `%mate-this` and

191`%mate-that`, but those don't exist yet.

196`%mate-that`, but those don't exist yet.

192

197

193### Autosync

198### Autosync

194

199

195Usage:

200Usage:

201+

196```

202```

197|sync %target-desk ~source-ship %source-desk

203|sync %target-desk ~source-ship %source-desk

198```

204```