@@ -10,132 +10,140 @@ 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`](@/docs/glossary/desk.md) is something like an independently
23+revision-controlled branch of your urbit's file-system. Your urbit's system
24+files live in the `%home` `desk`.
25+
1926It's important to note that whenever you want to sync changes from your Unix
2027directory to your ship, you must use the `|commit %desk` command, where `%desk`
21−is the desk that you'd like to sync to.
28+is the `desk` that you'd like to sync to.
2229
23−When developing it's a good idea to use a separate desk. Create a `%sandbox`
24−desk based on the `%home` desk:
30+When developing it's a good idea to use a separate `desk`. Create a `%sandbox`
31+`desk` based on the `%home` `desk`:
2532
2633```
27−~your-urbit:dojo> |merge %sandbox ~your-urbit %home
34+~zod:dojo> |merge %sandbox ~zod %home
2835```
2936
3037Running `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.
38+command instead of typing out the entire thing. This is especially useful for
39+comets due to their very long names.
3340
3441```
35−~your-urbit:dojo> |merge %sandbox our %home
42+~zod:dojo> |merge %sandbox our %home
3643```
3744
3845Most of the time we want to use Clay from Unix. Mount the entire contents of
3946your `sandbox` desk to Unix:
4047
4148```
42−~your-urbit:dojo> |mount /=sandbox=
49+~zod:dojo> |mount /=sandbox=
4350```
4451
4552To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`
4653displays files in the current directory, and `+cat` displays the contents of
4754a file.
4855
49−We can use `%` to mean "current directory." The result of the command below
56+We use `%` to mean "current directory." The result of the command below
5057is just like using `ls` in a Unix terminal.
5158
5259```
53−~your-urbit:dojo> +ls %
60+~zod:dojo> +ls %
5461```
5562
5663Notice how `+cat %` does the same thing. That's because everything in Clay,
5764including directories, is a file.
5865
59−Sync from your friend `~some-ship`'s `%experiment` desk to your
60−`%sandbox` desk:
66+Sync from your friend `~bus`'s `%experiment` desk to your `%sandbox` desk:
6167
6268```
63−~your-urbit:dojo> |sync %sandbox ~some-ship %experiment
69+~zod:dojo> |sync %sandbox ~bus %experiment
6470```
6571
6672If and when your sync is successful, you will receive a message:
6773
6874```
69−activated sync from %experiment on ~some-ship to %sandbox
75+kiln: sync succeeded from %experiment on ~bus to %sandbox
7076```
7177
7278The ship that you sync from will get their own message indicating that you're
7379both connected as peers:
7480
7581```
76−; ~your-urbit is your neighbor.
82+; ~zod is your neighbor.
7783```
7884
7985---
8086
8187### Clay manual
8288
89+The following constitutes an explanation of handy commands that most Urbit
90+pilots will want to know at some point. Reading this section will get you to the
91+point that you can navigate the file system, sync with Unix, merge your desk,
92+and other basic tasks familiar to novice users of the Unix terminal.
93+
8394#### Paths
8495
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.
96+A path in Clay is a list of URL-safe text, restricted to the characters `[a
97+z]`,`[0 9]`, `.`, `-`, `_`, and `~`. This path is a list of strings each
98+prepended by `/`. In other words, paths are expressed as `/foo/bar/baz`. File
99+extensions are separated from file names with `/`, not `.`. Extensions are
100+syntactically identical to subdirectories, except that they must terminate the
101+path.
91102
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`.
103+Paths begin with three strings indicating the ship, desk, and revision, and
104+might look like `/~dozbud-namsep/home/11`.
95105
96−The first `beak` component is `ship`, which is, as you might guess, the name of
106+The first component is `ship`, which is, as you might guess, the name of
97107an 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;
108+contain other directories; the default `desk` is `%home`. The third component is
109+the revision, which represents version information in various ways: date and time;
100110a version sequence, which is a value incremented by one whenever a file on the
101111given `desk` is modified; or an arbitrary plaintext label.
102112
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.
113+You can find what your current ship, desk, and revision is at any given moment by
114+typing `%` in the Dojo and looking at the first three results. This will display
115+as a cell rather than a path, like
116+```
117+[~.~zod ~.home ~.~2021.3.19..16.11.20..0c60]
118+```
119+Here we see that the revision consists of the date, time, and a short hash.
105120
106−We use `beak`s because, unlike the current internet, the Urbit network uses a
121+We use this format because, unlike the current internet, the Urbit network uses a
107122global namespace. That means that a file named `example.hoon` in the `/gen`
108123directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
109124universal address to anyone else on the network:
110125`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of
111126course, doesn't mean that everyone on the network has privileges to access that
112−path.
127+path. But given the revision-controlled and immutable nature of Urbit, this
128+means that if the file requested is available, it will always be the same. This
129+means that if an Urbit is serving a webpage, that exact version will always be
130+retrievable (assuming you have access to it).
113131
114−The structure that combines a `beak` with further path information is called a
115−`beam`.
116132
117133#### Relative paths
118134
119135The `%` 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−```
136+**relative path**, which is the path where you are currently working.
129137
130138`%`s can be stacked to indicate one level further up in the hierarchy for each
131139additional `%`. Try the following command:
132140
133141```
134−~your-planet:dojo> %%%
142+~zod:dojo> %%%
135143```
136144
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
145+You'll notice that it only has your ship name and the empty list. The
146+two additional `%`s abandoned the revision and the `desk` information by moving
139147up twice the hierarchy.
140148
141149There are no local relative paths. `/foo/bar` must be written as
@@ -147,29 +155,31 @@ You don't need to write out the explicit path every time you want to reference
147155somewhere outside of your working directory. You can substitute `=` for the
148156segments of a path.
149157
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:
158+Recall that a full address in the the Urbit namespace is of the form
159+`/ship/desk/case/path`. To switch to the `%sandbox` `desk`, you would enter
153160
154161```
155−~your-urbit:dojo> =dir /=sandbox=
162+~sampel-palnet:dojo> =dir /=sandbox=
156163```
157164
165+`=dir` is used to change the working directory - we will see more on it
166+[below](#changing-directories.)
167+
158168The above command uses substitution to use your current `ship` and
159−`case`; only the `desk` argument, which is located between the other two, is
169+revision; only the `desk` argument, which is located between the other two, is
160170given something new. Without substitution, you would need to write:
161171
162172```
163−~your-urbit:dojo> =dir /~your-urbit/sandbox/85
173+~sampel-palnet:dojo> =dir /~sampel-palnet/sandbox/85
164174```
165175
166−Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
176+Substitutions work the same way in the `ship/desk/case` and
167177paths. For example, if you are in the `/gen` directory, you can reference a file
168178in the `/app` directory like below. (`+cat` displays the contents of a file).
169179
170180```
171−~your-urbit:dojo> =dir %/gen
172−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> +cat /===/app/curl/hoon
181+~sampel-palnet:dojo> =dir %/gen
182+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen> +cat /===/app/curl/hoon
173183```
174184
175185Note what was substituted out, and note that we don't need to separate `=` with
@@ -179,8 +189,8 @@ If we changed our working directory to something called `/gen/gmail`, we could
179189access a file called
180190
181191```
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
192+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen> =dir %/gmail
193+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/gmail> +cat /===/app/=/split/hoon
184194```
185195
186196Because both paths share a directory named `/gmail` at the same position in the
@@ -192,11 +202,11 @@ We can do the same thing between desks. If `%sandbox` has been merged with
192202command.
193203
194204```
195−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /=sandbox=/app/=/split/hoon
205+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/gmail> +cat /=sandbox=/app/=/split/hoon
196206```
197207
198208Most 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`
209+number in the `dojo`: `/~lodleb-ritrul/home/~2021.3.19..16.11.20..0c60/gen/example/hoon`
200210
201211#### Changing directories
202212
@@ -205,23 +215,23 @@ Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.
205215For example, the syntax to navigate to `/home/gen/ask` is:
206216
207217```
208−~your-urbit:dojo> =dir /=home=/gen/ask
218+~sampel-palnet:dojo> =dir /=home=/gen/ask
209219```
210220
211221This command will turn your prompt into something like this:
212222
213223```
214−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask>
224+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/ask>
215225```
216226
217227Using `=dir` without anything else uses the null path, which returns you to
218228your home desk.
219229
220230```
221−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask> =dir
231+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen/ask> =dir
222232```
223233
224−Your dojo prompt will turn back into `~your-urbit:dojo>`.
234+Your dojo prompt will turn back into `~sampel-palnet:dojo>`.
225235
226236To go up levels in the path hierarchy, recall the relative path expression
227237`%`. Stacking them represents another level higher in the hierarchy than
@@ -229,22 +239,23 @@ the current working directory for each `%` beyond the initial. The command below
229239brings you one level up:
230240
231241```
232−~your-urbit:dojo> =dir %/gen
233−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %%
242+~sampel-palnet:dojo> =dir %/gen
243+~sampel-palnet:dojo/=/=/~2021.3.19..16.11.20..0c60/gen> =dir %%
234244```
235245
236246### Revision-control
237247
238248#### Mount
239249
240−Syntax: `|mount /clay/path [Unix-name]`
250+Syntax: `|mount %/clay/path %mount-point`
241251
242−Mount the `clay-path` at the Unix mount point `Unix-name`.
252+Mount the `/clay/path` at the Unix mount point `mount-point` with your pier as
253+root directory.
243254
244255**Examples:**
245256
246257```
247−|mount %/gen generators
258+|mount %/gen %generators
248259```
249260
250261Mounts `%/gen` to `/generators` inside your pier directory.
@@ -274,57 +285,65 @@ Unmounts the Unix path `/generators`.
274285#### Merge
275286
276287```
277−|merge desk beak[, =gem strategy]
288+|merge %target-desk ~source-ship %source-desk
278289```
279290
280−Merges a `beak` into a `desk` using an optional merge `strategy`.
291+Merges a source `desk` into a target `desk`.
281292
282−A `beak` is a ship-desk-case triple, encoded as a
283−path(`/~dozbud/home/2`)
293+This can optionally include a [merge
294+strategy](@/docs/arvo/clay/using.md#strategies):
284295
285−**Examples:**
296+```
297+|merge %target-desk ~source-ship %source-desk, =gem %strategy
298+```
299+
300+You may also merge a Clay path on your own ship to a `desk`, along with an
301+optional strategy.
286302
287303```
288−|merge %home-work /=home=, =gem %fine
304+|merge %target-get %/clay/path, =gem %strategy
289305```
290306
291−Merge `/=home=` into `%home-work` using merge strategy `%fine`.
307+**Examples:**
292308
293309```
294310|merge %examples ~wacbex-ribmex %examples
295311```
296312
297−Merge the `%examples` desk from `~waxbex-ribmex`
313+Merge the `%examples` `desk` from `~waxbex-ribmex`
314+
315+```
316+|merge %home-work /=home=, =gem %fine
317+```
318+
319+Merge `/=home=` into `%home-work` using merge strategy `%fine`.
320+
298321
299322#### Sync
300323
301324```
302−|sync desk plot [plot-desk]
325+|sync %target-desk ~source-ship %target-desk
303326```
304327
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
328+Subscribe to continuous updates from remote `desk` on local `desk`. Non-comet
329+urbits have `|sync %home ~sponsor %kids` automatically set up (where `~sponsor`
330+is the planet that issued a moon, the star that issued a planet, or the galaxy
310331that issued a star).
311332
312333**Examples:**
313334
314335```
315336|sync %home-local ~dozbud %home
316−
317−|sync %home ~doznec
318337```
319338
320339#### Unsync
321340
322341```
323−|unsync desk plot [plot-desk]
342+|unsync %target-desk ~source-ship %source-desk
324343```
325344
326−Unsubscribe from updates from remote `plot` on local `desk` with
327−optional `plot-desk`. Arguments must match original `|sync` command.
345+Unsubscribe from updates from remote `desk` on local `desk`. Arguments must
346+match original `|sync` command.
328347
329348Example:
330349
@@ -332,23 +351,7 @@ Example:
332351|unsync %home-local ~dozbud %home
333352```
334353
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
350354
351−See [Clay merge strategies](@/docs/arvo/clay/using.md#merging).
352355### Manipulation
353356
354357#### `+cat`
@@ -368,7 +371,7 @@ Similar to Unix `ls`. `+ls` takes a single `path`.
368371Produces a list of names at the `path`.
369372
370373```
371−~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
374+~sampel-palnet:dojo> +cat %/our/home/gen/curl/hoon
372375```
373376
374377#### `|rm`