@@ -10,132 +10,139 @@ referentially transparent namespace. An easy way to think about it is like typed
1010
1111The most common way to use Clay is to mount a Clay node in a Unix directory. The mounted directory is always at the root of your pier directory.
1212
13+For more information on Clay, see the [Overview](@/docs/arvo/clay/clay.md), and
14+additional usage information at [Using Clay](@/docs/arvo/clay/using.md).
15+
1316### Quickstart
1417
1518This quick-start guide will walk you through some common commands. Follow along
1619using your Dojo. When you get a `>=` message after entering a command, this means
1720that the command was successful.
1821
22+A `desk` is something like an independently revision-controlled branch of your
23+urbit's file-system. Your urbit's system files live in the `%home` `desk`.
24+
1925It's important to note that whenever you want to sync changes from your Unix
2026directory to your ship, you must use the `|commit %desk` command, where `%desk`
21−is the desk that you'd like to sync to.
27+is the `desk` that you'd like to sync to.
2228
23−When developing it's a good idea to use a separate desk. Create a `%sandbox`
24−desk based on the `%home` desk:
29+When developing it's a good idea to use a separate `desk`. Create a `%sandbox`
30+`desk` based on the `%home` `desk`:
2531
2632```
27−~your-urbit:dojo> |merge %sandbox ~your-urbit %home
33+~zod:dojo> |merge %sandbox ~zod %home
2834```
2935
3036Running `our` produces your ship-name, meaning that you can run the following
31−command instead of typing out the entire thing. Useful for comets due to their
32−very long names.
37+command instead of typing out the entire thing. This is especially useful for
38+comets due to their very long names.
3339
3440```
35−~your-urbit:dojo> |merge %sandbox our %home
41+~zod:dojo> |merge %sandbox our %home
3642```
3743
3844Most of the time we want to use Clay from Unix. Mount the entire contents of
3945your `sandbox` desk to Unix:
4046
4147```
42−~your-urbit:dojo> |mount /=sandbox=
48+~zod:dojo> |mount /=sandbox=
4349```
4450
4551To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`
4652displays files in the current directory, and `+cat` displays the contents of
4753a file.
4854
49−We can use `%` to mean "current directory." The result of the command below
55+We use `%` to mean "current directory." The result of the command below
5056is just like using `ls` in a Unix terminal.
5157
5258```
53−~your-urbit:dojo> +ls %
59+~zod:dojo> +ls %
5460```
5561
5662Notice how `+cat %` does the same thing. That's because everything in Clay,
5763including directories, is a file.
5864
59−Sync from your friend `~some-ship`'s `%experiment` desk to your
60−`%sandbox` desk:
65+Sync from your friend `~bus`'s `%experiment` desk to your `%sandbox` desk:
6166
6267```
63−~your-urbit:dojo> |sync %sandbox ~some-ship %experiment
68+~zod:dojo> |sync %sandbox ~bus %experiment
6469```
6570
6671If and when your sync is successful, you will receive a message:
6772
6873```
69−activated sync from %experiment on ~some-ship to %sandbox
74+kiln: sync succeeded from %experiment on ~bus to %sandbox
7075```
7176
7277The ship that you sync from will get their own message indicating that you're
7378both connected as peers:
7479
7580```
76−; ~your-urbit is your neighbor.
81+; ~zod is your neighbor.
7782```
7883
7984---
8085
8186### Clay manual
8287
88+The following constitutes an explanation of handy commands that most Urbit
89+pilots will want to know at some point. Reading this section will get you to the
90+point that you can navigate the file system, sync with Unix, merge your desk,
91+and other basic tasks familiar to novice users of the Unix terminal.
92+
8393#### Paths
8494
85−A path in Clay is a list of URL-safe text, restricted to the characters
86−`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
87−meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
88−In other words, paths are expressed as `/foo/bar/baz`. File extensions are
89−separated from file names with `/`, not `.`. Extensions are syntactically
90−identical to subdirectories, except that they must terminate the path.
95+A path in Clay is a list of URL-safe text, restricted to the characters `[a
96+z]`,`[0 9]`, `.`, `-`, `_`, and `~`. This path is a list of strings each
97+prepended by `/`. In other words, paths are expressed as `/foo/bar/baz`. File
98+extensions are separated from file names with `/`, not `.`. Extensions are
99+syntactically identical to subdirectories, except that they must terminate the
100+path.
91101
92−Paths begin with a piece of data called a `beak`. A beak is formally a
93−`(p=ship q=desk r=case)`; it has three components, and might look like
94−`/~dozbud-namsep/home/11`.
102+Paths begin with three strings indicating the ship, desk, and revision, and
103+might look like `/~dozbud-namsep/home/11`.
95104
96−The first `beak` component is `ship`, which is, as you might guess, the name of
105+The first component is `ship`, which is, as you might guess, the name of
97106an Urbit ship. The second component is `desk`, which is a workspace meant to
98−contain other directories; the default desk is `%home`. The third component is
99−`case`, which represents version information in various ways: date and time;
107+contain other directories; the default `desk` is `%home`. The third component is
108+the revision, which represents version information in various ways: date and time;
100109a version sequence, which is a value incremented by one whenever a file on the
101110given `desk` is modified; or an arbitrary plaintext label.
102111
103−You can find what your `beak` is at any given moment by
104−typing `%` in the Dojo and looking at the first three results.
112+You can find what your current ship, desk, and revision is at any given moment by
113+typing `%` in the Dojo and looking at the first three results. This will display
114+as a cell rather than a path, like
115+```
116+[~.~zod ~.home ~.~2021.3.19..16.11.20..0c60]
117+```
118+Here we see that the revision consists of the date, time, and a short hash.
105119
106−We use `beak`s because, unlike the current internet, the Urbit network uses a
120+We use this format because, unlike the current internet, the Urbit network uses a
107121global namespace. That means that a file named `example.hoon` in the `/gen`
108122directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
109123universal address to anyone else on the network:
110124`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of
111125course, doesn't mean that everyone on the network has privileges to access that
112−path.
126+path. But given the revision-controlled and immutable nature of Urbit, this
127+means that if the file requested is available, it will always be the same. This
128+means that if an Urbit is serving a webpage, that exact version will always be
129+retrievable (assuming you have access to it).
113130
114−The structure that combines a `beak` with further path information is called a
115−`beam`.
116131
117132#### Relative paths
118133
119134The `%` command, which we gestured at in the above section, represents the
120−**relative path**, which is the path where you are currently working. If your
121−working directory is just your home desk, indicated by the
122−prompt `~your-planet:dojo>`, then running the command below will print your
123−working directory's `beam` information: your `beak`, and a `~` that represents
124−the empty list since no path is present.
125−
126−```
127−~your-urbit:dojo> %
128−```
135+**relative path**, which is the path where you are currently working.
129136
130137`%`s can be stacked to indicate one level further up in the hierarchy for each
131138additional `%`. Try the following command:
132139
133140```
134−~your-planet:dojo> %%%
141+~zod:dojo> %%%
135142```
136143
137−You'll probably notice that it only has your ship name and the empty list. The
138−two additional `%`s abandoned the `case` and the `desk` information by moving
144+You'll notice that it only has your ship name and the empty list. The
145+two additional `%`s abandoned the revision and the `desk` information by moving
139146up twice the hierarchy.
140147
141148There are no local relative paths. `/foo/bar` must be written as
@@ -147,29 +154,31 @@ You don't need to write out the explicit path every time you want to reference
147154somewhere outside of your working directory. You can substitute `=` for the
148155segments of a path.
149156
150−Recall that a full address in the the Urbit namespace is a `beam`: the
151−`/ship/desk/case/path`. If you've switched to another desk before, you're
152−already familiar with substitution syntax:
157+Recall that a full address in the the Urbit namespace is of the form
158+`/ship/desk/case/path`. To switch to the `%sandbox` `desk`, you would enter
153159
154160```
155−~your-urbit:dojo> =dir /=sandbox=
161+~sampel-palnet:dojo> =dir /=sandbox=
156162```
157163
164+`=dir` is used to change the working directory - we will see more on it
165+[below](#changing-directories.)
166+
158167The above command uses substitution to use your current `ship` and
159−`case`; only the `desk` argument, which is located between the other two, is
168+revision; only the `desk` argument, which is located between the other two, is
160169given something new. Without substitution, you would need to write:
161170
162171```
163−~your-urbit:dojo> =dir /~your-urbit/sandbox/85
172+~sampel-palnet:dojo> =dir /~sampel-palnet/sandbox/85
164173```
165174
166−Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
175+Substitutions work the same way in the `ship/desk/case` and
167176paths. For example, if you are in the `/gen` directory, you can reference a file
168177in the `/app` directory like below. (`+cat` displays the contents of a file).
169178
170179```
171−~your-urbit:dojo> =dir %/gen
172−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> +cat /===/app/curl/hoon
180+~sampel-palnet:dojo> =dir %/gen
181+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen> +cat /===/app/curl/hoon
173182```
174183
175184Note what was substituted out, and note that we don't need to separate `=` with
@@ -179,8 +188,8 @@ If we changed our working directory to something called `/gen/gmail`, we could
179188access a file called
180189
181190```
182−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %/gmail
183−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /===/app/=/split/hoon
191+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen> =dir %/gmail
192+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/gmail> +cat /===/app/=/split/hoon
184193```
185194
186195Because both paths share a directory named `/gmail` at the same position in the
@@ -192,11 +201,11 @@ We can do the same thing between desks. If `%sandbox` has been merged with
192201command.
193202
194203```
195−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /=sandbox=/app/=/split/hoon
204+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/gmail> +cat /=sandbox=/app/=/split/hoon
196205```
197206
198207Most commonly this is used to avoid having to know the current revision
199−number in the `dojo`: `/~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example/hoon`
208+number in the `dojo`: `/~lodleb-ritrul/home/~2021.3.19..16.11.20..0c60/gen/example/hoon`
200209
201210#### Changing directories
202211
@@ -205,23 +214,23 @@ Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.
205214For example, the syntax to navigate to `/home/gen/ask` is:
206215
207216```
208−~your-urbit:dojo> =dir /=home=/gen/ask
217+~sampel-palnet:dojo> =dir /=home=/gen/ask
209218```
210219
211220This command will turn your prompt into something like this:
212221
213222```
214−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask>
223+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/ask>
215224```
216225
217226Using `=dir` without anything else uses the null path, which returns you to
218227your home desk.
219228
220229```
221−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask> =dir
230+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/ask> =dir
222231```
223232
224−Your dojo prompt will turn back into `~your-urbit:dojo>`.
233+Your dojo prompt will turn back into `~sampel-palnet:dojo>`.
225234
226235To go up levels in the path hierarchy, recall the relative path expression
227236`%`. Stacking them represents another level higher in the hierarchy than
@@ -229,22 +238,23 @@ the current working directory for each `%` beyond the initial. The command below
229238brings you one level up:
230239
231240```
232−~your-urbit:dojo> =dir %/gen
233−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %%
241+~sampel-palnet:dojo> =dir %/gen
242+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen> =dir %%
234243```
235244
236245### Revision-control
237246
238247#### Mount
239248
240−Syntax: `|mount /clay/path [Unix-name]`
249+Syntax: `|mount %/clay/path %mount-point`
241250
242−Mount the `clay-path` at the Unix mount point `Unix-name`.
251+Mount the `/clay/path` at the Unix mount point `mount-point` with your pier as
252+root directory.
243253
244254**Examples:**
245255
246256```
247−|mount %/gen generators
257+|mount %/gen %generators
248258```
249259
250260Mounts `%/gen` to `/generators` inside your pier directory.
@@ -274,57 +284,65 @@ Unmounts the Unix path `/generators`.
274284#### Merge
275285
276286```
277−|merge desk beak[, =gem strategy]
287+|merge %target-desk ~source-ship %source-desk
278288```
279289
280−Merges a `beak` into a `desk` using an optional merge `strategy`.
290+Merges a source `desk` into a target `desk`.
281291
282−A `beak` is a ship-desk-case triple, encoded as a
283−path(`/~dozbud/home/2`)
292+This can optionally include a [merge
293+strategy](@/docs/arvo/clay/using.md#strategies):
284294
285−**Examples:**
295+```
296+|merge %target-desk ~source-ship %source-desk, =gem %strategy
297+```
298+
299+You may also merge a Clay path on your own ship to a `desk`, along with an
300+optional strategy.
286301
287302```
288−|merge %home-work /=home=, =gem %fine
303+|merge %target-get %/clay/path, =gem %strategy
289304```
290305
291−Merge `/=home=` into `%home-work` using merge strategy `%fine`.
306+**Examples:**
292307
293308```
294309|merge %examples ~wacbex-ribmex %examples
295310```
296311
297−Merge the `%examples` desk from `~waxbex-ribmex`
312+Merge the `%examples` `desk` from `~waxbex-ribmex`
313+
314+```
315+|merge %home-work /=home=, =gem %fine
316+```
317+
318+Merge `/=home=` into `%home-work` using merge strategy `%fine`.
319+
298320
299321#### Sync
300322
301323```
302−|sync desk plot [plot-desk]
324+|sync %target-desk ~source-ship %target-desk
303325```
304326
305−Subscribe to continuous updates from remote `plot` on local `desk`.
306−`plot-desk` can specify the remote `desk` name. When omitted it defaults
307−to being the same as `desk`. Non-comet urbits have
308−`|sync %home ~parent %kids` automatically set up (where `~parent` is the
309−planet that issued a moon, the star that issued a planet, or the galaxy
327+Subscribe to continuous updates from remote `desk` on local `desk`. Non-comet
328+urbits have `|sync %home ~sponsor %kids` automatically set up (where `~sponsor`
329+is the planet that issued a moon, the star that issued a planet, or the galaxy
310330that issued a star).
311331
312332**Examples:**
313333
314334```
315335|sync %home-local ~dozbud %home
316−
317−|sync %home ~doznec
318336```
319337
320338#### Unsync
321339
322340```
323−|unsync desk plot [plot-desk]
341+|unsync %target-desk ~source-ship %source-desk
324342```
325343
326−Unsubscribe from updates from remote `plot` on local `desk` with
327−optional `plot-desk`. Arguments must match original `|sync` command.
344+Unsubscribe from updates from remote `desk` on local `desk`. Arguments must
345+match original `|sync` command.
328346
329347Example:
330348
@@ -332,23 +350,7 @@ Example:
332350|unsync %home-local ~dozbud %home
333351```
334352
335−#### Label
336−
337−```
338−|label desk name
339−```
340−
341−Label the current version of `desk` `name`.
342−
343−Example:
344−
345−```
346−|label %home release
347−```
348−
349−### Merge strategies
350353
351−See [Clay merge strategies](@/docs/arvo/clay/using.md#merging).
352354### Manipulation
353355
354356#### `+cat`
@@ -368,7 +370,7 @@ Similar to Unix `ls`. `+ls` takes a single `path`.
368370Produces a list of names at the `path`.
369371
370372```
371−~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
373+~sampel-palnet:dojo> +cat %/our/home/gen/curl/hoon
372374```
373375
374376#### `|rm`