@@ -25,325 +25,133 @@ a Unix directory. The Urbit process will watch this directory
2525and automatically record edits as changes, Dropbox style. The
2626mounted directory is always at the root of your pier directory.
2727
28−## Commands
28+## Quickstart
2929
30−Note that in both commands and generators, a currently unbound
31−case (such as a version in the future) will make the calculation
32−block, not complete. A remote case will cause a network request.
33−A remote, unbound case will cause a waiting subscription.
30+Most of the time we want to use `%clay` from Unix.
3431
35−### Mounting to Unix
32+Mount the entire contents of your `home` desk to Unix:
3633
37−#### `|mount [pax=path pot=$|(~ [knot ~])]`
34+ ~fintud-macrep:dojo>|mount %
3835
39−Mount the path `pax` at the Unix mount point `pot`, the name of a
40−subdirectory in your pier.
36+To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:
4137
42− |mount %/pub/doc %documents
38+ ~fintud-macrep:dojo> +ls /=home=/web
4339
44−with a `$PIER` of `/home/nixon/urbit/fintud-macrep`, will mount
45−`%/pub/doc` in `/home/nixon/urbit/fintud-macrep/documents`.
40+Let's see the contents of `/=home=/web/md`:
4641
47−The mount point is optional; if it's not supplied, the last knot
48−in the path (`%doc`) will be used.
42+ ~fintud-macrep:dojo> +cat /=home=/web/md
4943
50−#### `|unmount [mon=$|(term [knot path]) ~] `
44+Create a new desk:
5145
52−Undo a mount, either by specifying the path or the mount point:
46+ |merge %sandbox ~fintud-macrep %sandbox
5347
54− |unmount %/pub/doc
55− |unmount %documents
48+Sync it with a remote desk on the network:
5649
57−It's a good habit to also delete the Unix subtree, but Urbit
58−doesn't do it for you.
50+ |sync %sandbox ~wactex-ribmex %examples
5951
60−### Revision-control operations
52+## Manual
6153
62−#### `|merge [syd=desk src=beak how=$|(~ [germ ~])]`
54+<h3 class="first child">Paths</h3>
6355
64−Merge the beak `src` into the desk `syd`, with optional merge
65−strategy `how`.
56+A path in `%clay` is a list of URL-safe text, restricted to `[a z]`,`[0 9]`, `.`, `-`, `_` and `~`. Formally this is a `(list knot)` where each segment is a `@ta`.
6657
67−The `src` beak can be a desk (`%home`); a plot-desk cell
68−(`[~doznec %home]`); or a plot-desk-case path (`/=home=`).
58+Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`. The first three segments of an urbit path are `/plot/desk/case`, for example `/~doznec/home/1`.
6959
70− |merge %home-work /=home= %fine
71− |merge %home-work /=home=
72−
73−#### `|sync [syd=desk her=plot org=$|(~ [desk ~])]`
74−
75−Activate autosync from the plot `her` and source desk `org`, into
76−the desk `syd`. If `org` is omitted, it's the same as `syd`:
77−
78− |sync %home-local ~doznec %home
79− |sync %home ~doznec
80−
81−Note that `|merge` takes a path because it needs a source case
82−(revision), which would make no sense for `|sync`.
83−
84−#### `|label [syd=desk lab=term]`
85−
86−Label the current version of desk `syd`:
87−
88−#### `|unsync [syd=desk her=plot org=desk ~]`
89−
90−Turn off autosync. The argument needs to match the original
91−`|sync` perfectly, or Urbit will become angry and confused.
92−
93−### Filesystem manipulation
94−
95−#### `|rm [paz=(list path)]`
96−
97−Remove any leaf at each of the paths in `paz`.
98−
99− |rm /===/pub/fab/nixon/hoon
100−
101−Remember that folders in `%clay` are a consequence of the tree of
102−leaves; there is no `rmdir` or `mkdir`.
103−
104−#### `|cp [too=path fro=path how=$|(~ [germ ~])]`
105−
106−Copy the subtree `fro` into the subtree `too`, committing it with
107−the specified merge strategy.
108−
109−#### `|mv [too=path fro=path how=$|(~ [germ ~])]`
110−
111−In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The
112−`|rm` doesn't happen unless the `|cp` succeeds, obviously -- it's
113−good to be transactional.
114−
115−### Filesystem generators
116−
117−#### `+cal [paz=(list path)]`
118−#### `+cat [pax=path]`
119−
120−Produce the noun, if any, at each of these (global) paths.
121−`+cat` produces one result, `+cal` a list.
122−
123−#### `+ls [pax=path ~]`
60+#### Relative paths
12461
125−Produce the list of names in the folder at `pax`.
62+Relative paths are expressed using `%` which is roughly equivalent to Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be. There are no local relative paths. `foo/bar` must be written `%/foo/bar`.
12663
127−Because generators aren't passed the dojo's default path, unlike
128−the current directory in Unix, it's not possible to build an
129−trivial `+ls` that's the equivalent of Unix `ls`. You always
130−have to write `+ls %`.
64+#### Substitution
13165
132−#### `+ll [pax=path ~]`
133−
134−Like `+ls`, but the result is a list of full paths. Useful as
135−Urbit equivalent of the Unix wildcard `*`.
136−
137−### Path format
66+If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`,
67+and `/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of
68+`/=/=/zoo` or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
13869
139−As a noun, a path in `%clay` is a `(list knot)`, where each
140−segment is an `@ta` atom -- URL-safe text, restricted to `[a z]`,
141−`[0 9]`, `.`, `-`, `_` and `~`. The list is a tuple terminated
142−with a Hoon null, `~`.
70+Most commonly this is used to avoid having to know the current revision number in the `dojo`. Instead of writing `/~fintud-macrep/home/4/path/to/file` you can just write `/=home=/path/to/file`.
14371
144−As an ordinary Hoon noun, `[%foo %bar %baz]` has this structure.
145−But Hoon also supports the Unix path syntax: `/foo/bar/baz` is
146−the same noun.
72+### Revision-control
14773
148−### Relative paths
74+<h3 class="first child"><code>|mount clay-path [unix-name]</code></h3>
14975
150−The Hoon path syntax is always defined relative to a default
151−path, which is configuration state in the Hoon parser. In
152−`:dojo`, this works a little like the Unix current directory.
76+Mount the `clay-path` at the unix mount point `unix-name`.
15377
154−(But note that in Unix, relative paths are expanded by the
155−application, which can read the current directory from the
156−environment. In Urbit, the current directory and variables are
157−hidden by the dojo from any code it runs. The parser generates
158−the absolute path -- more like the way a Unix shell parser
159−unglobs `*`.)
78+**Examples:**
16079
161−Relative path syntax: `%` is the default path (Unix `.`). `%%`
162−is the parent path (Unix `..`). Unix does not have `...`,
163−`....`, etc. But Urbit has `%%%`, `%%%%`, etc. Urbit has no
164−local relative paths; in Unix, `foo/bar` is a shorthand for
165−`./foo/bar`, but in Urbit you have to write `%/foo/bar`.
80+ |mount %/web
16681
167−Unix has no top-level substitution syntax, but Urbit does. If
168−the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`,
169−and `/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of
170−`/=/=/zoo` or `/=/=/=/voo`, write `/==zoo` or `/===voo`. Your
171−fingers have enough miles on them already.
82+Mounts `%/web` to `/web` inside your pier directory.
17283
173−### Beak
84+ |mount %/gen generators
17485
175−The top three knots in a `%clay` path are `/plot/desk/case`,
176−where `plot` is of course an urbit; `desk` is a branch name; and
177−`case` is a revision identity, which is either (a) a label, (b) a
178−date, or (c) a change number. For obscure reasons, this prefix
179−is called the `beak`.
86+Mounts `%/gen` to `/generators` inside your pier directory.
18087
181−### Spur
88+### `|unmount [clay-path || unix-name]`
18289
183−The rest of the path, or `spur`, navigates a tree of `node`
184−nouns. A `node` is like an inode in a Unix filesystem, but
185−different.
90+Unmount the path or name from Unix.
18691
187−An inode is *either* a file or a directory. A `node` is *both* a
188−folder (which may be empty) and an optional leaf (a noun).
92+**Examples:**
18993
190−There is no `rmdir` or `mkdir`; an empty node is automatically
191−pruned, and creating a node creates its path. The absence of a
192−file-or-directory mode bit eliminates all kinds of strange corner
193−cases, especially in merging.
94+ |unmount %/web
19495
195−### Leaf
96+Unmounts the path `%/web` from whatever name it was mounted as.
19697
197−`%clay` is a typed filesystem, or more precisely a *marked* one.
198−When we sync Unix and Urbit paths, we convert a Unix file extension
199−(an informal specifications) into a Urbit `*mark*` (an
200−executable specification)
98+ |unmount %generators
20199
202−The mark name is actually the last knot in the path. Or to put
203−it differently: if any `%clay` node has a leaf, its name within
204−its parent is its mark.
100+Unmounts the Unix path `/generators`.
205101
206−This is ridiculously confusing without examples. Suppose we have
207−the following Unix files, with directories to match:
102+### `|merge desk beak [strategy]`
208103
209− doc.md
210− doc/intro.md
211− doc/start.md
104+Merges a `beak` into a `desk` using an optional merge `strategy`.
212105
213−These become the Urbit files
106+A `beak` is either a desk (`%home`), a plot-desk cell (`[~doznec %home]`), or a plot-desk-case (`/~doznec/home/2/web/md`)
214107
215− %/doc/md
216− %/doc/intro/md
217− %/doc/start/md
218−
219−The folder map of the `%/doc` node contains three entries: `%md`,
220−`%intro`, `%start`. The folder of `%/doc/intro` and that of
221−`%/doc/start` each contain one entry: `%md` (the mark of an atom
222−in Markdown syntax).
108+**Examples:**
223109
224−Perhaps this example helps explains *why* `%clay` uses this node
225−design. One, it's a simple index-page model for any kind of
226−published tree. Two, this tree can expand its leaves smoothly,
227−just by adding content: if we decided `%/doc/start` was not a
228−leaf but a tree, we could just add `%/doc/start/child/md`.
110+ |merge %home-work /=home= %fine
229111
230−And three, the `%clay` node structure syncs invertibly with an
231−equivalent, and not unduly weird, Unix inode layout.
112+Merge `/=home=` into `%home-work` using merge strategy `%fine`.
232113
233−### Mounting to Unix
114+ |merge %examples [~wacbex-ribmex %examples]
234115
235−The most convenient way of interacting with `%clay` is mounting
236−it to Unix, and modifying it with Unix tools. The mount
237−directory is a flat subdirectory of your Urbit pier.
116+Merge the `%examples` desk from `~waxbex-ribmex`
238117
239−When you have a live mount point, Urbit monitors it with
240−`inotify()` or equivalent. (It would be neat to have a FUSE
241−driver, but we don't.) If you shut your urbit off, it will
242−recheck the mount point when it reloads.
118+### `|sync desk plot [plot-desk]`
243119
244−Unix files beginning with `.`, with no extension, with an
245−extension that doesn't map to an Urbit mark, or containing data
246−that doesn't validate to the mark, are ignored. Depending on the
247−extension, there may be a more or less complex conversion from
248−the Unix length/bytestream pair to the Urbit noun.
120+Subscribe to continuous updates from remote `plot` on local `desk`. `plot-desk` can specify the remote `desk` name. When omitted it's assumed to be the same as `desk`.
249121
250−### More about desks and marks
122+**Examples:**
251123
252−The Hoon source code for a mark like `%md` is in
253−`/===/mar/md/hoon`. But relative to what beak? What's in the
254−`/===`?
124+ |sync %home-local ~doznec %home
125+ |sync %home ~doznec
255126
256−The mark source of a leaf in `%clay` is always relative to its
257−own plot, desk and case. For example, a leaf at
127+### `|unsync desk plot [plot-desk]`
258128
259− `/~fintud-macrep/home/31/pub/doc/hello/md`
129+Unsubscribe from updates from remote `plot` on local `desk` with optional `plot-desk`. Arguments must match original `|sync` command exactly.
260130
261−is controlled by the mark source
131+Example:
262132
263− `/~fintud-macrep/home/31/mar/md/hoon`
133+ |unsync %home-local ~doznec %home
264134
265−If there is no such file or it doesn't compile, the mark is
266−effectively treated as `%noun`, ie, an arbitrary value.
135+### `|label desk name`
267136
268−(Note that when updating a mark, any update which shrinks the set
269−of nouns in that mark needs to at least adapt old nouns to new.
270−Also, mark source updates should be very slow, but aren't. They
271−should validate all nouns against the new mark, but don't.)
137+Label the current version of `desk` `name`.
272138
273−What can you do with a mark? Validate an arbitrary noun; perform
274−diffs, patches, and and conflict merges; transform to or from
275−another mark. The `%ford` vane, which builds and converts nouns,
276−can even discover and apply multi-step conversion paths.
139+Example:
277140
278−Marks are also used to describe network messages. In this case,
279−the mark source beak is the beak of the receiving urbit.
141+ |label %home release
280142
281−### Desks and merging
282143
283−As in any git-shaped revision control system, the core operation
284−of the system is merging.
144+### Merge strategies
285145
286−One of the effects of same-beak marks is that it doesn't make
287−sense to create an empty desk. You can't populate an empty desk
288−properly with typed files. Instead, a new desk should be merged
289−from an existing desk -- normally the default desk, `%home`.
290−
291−It's also generally bad style to edit directly in the desk you
292−want to modify. Your Unix filesystem changes will appear as a
293−stream of small, unstructured changes. You should be editing a
294−working desk. Conventionally, to change `%home`, merge `%home`
295−into `%home-work`, edit there, and merge back as a "commit."
296−Ideally, your "commits" include modifications to a text file that
297−acts as a changelog.
298−
299−So merges are important. Again as in `git`, merge strategies are
300−important. That said, if you are not doing exciting things with
301−`%clay`, you can skip the strategy subsection. By default,
302−`%clay` will always use the `%auto` meta-strategy, which will
303−always work if you're not doing exciting things.
304−
305−#### Merge strategies
306−
307−There are seven different merge strategies. Throughout our
308−discussion, we'll say that the merge is from Alice's desk to
309−Bob's.
310−
311−##### Direct strategies
312−
313−A `%init` merge should be used iff it's the first commit to a
314−desk. The head of Alice's desk is used as the number 1 commit to
315−Bob's desk. Obviously, the ancestry remains intact when
316−traversing the parentage of the commit, even though previous
317−commits are not numbered for Bob's desk.
318−
319−A `%this` merge means to keep what's in Bob's desk, but join the
320−ancestry. Thus, the new commit has the head of each desk as
321−parents, but the data is exactly what's in Bob's desk. For those
322−following along in git, this is the 'ours' merge strategy, not
323−the '--ours' option to the 'recursive' merge strategy. In other
324−words, even if Alice makes a change that does not conflict with
325−Bob, we throw it away.
146+`%init` - Used iff it's the first commit to a desk.
326147
327−A `%that` merge means to take what's in Alice's desk, but join
328−the ancestry. This is the reverse of `%this`.
148+`%this` - Keep what's in Bob's desk, but join the ancestry.
329149
330−A `%fine` merge is a "fast-forward" merge. This succeeds iff one
331−head is in the ancestry of the other. In this case, we use the
332−descendant as our new head.
150+`%that` - take what's in Alice's desk, but join the ancestry. This is the reverse of `%this`.
333151
334−For `%meet`, `%mate`, and `%meld` merges, we first find the most
335−recent common ancestor to use as our merge base. If we have no
336−common ancestors, then we fail. If we have multiple most
337−recent common ancestors, then we have a criss-cross situation,
338−which should be handled delicately. At present, we don't handle
339−this kind of situation, but something akin to git's 'recursive'
340−strategy should be implemented in the future.
152+`%fine` - "fast-forward" merge. This succeeds iff one head is in the ancestry of the other.
341153
342−There's a functional inclusion ordering on `%fine`, `%meet`,
343−`%mate`, and `%meld` such that if an earlier strategy would have
344−succeeded, then every later strategy will produce the same
345−result. Put another way, every earlier strategy is the same as
346−every later strategy except with a restricted domain.
154+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to use as our merge base.
347155
348156A `%meet` merge only succeeds if the changes from the merge base
349157to Alice's head (hereafter, "Alice's changes") are in different
@@ -367,46 +175,37 @@ data is the merge base plus Alice's changed files plus Bob's
367175changed files plus the successfully merged files plus the merge
368176base's version of the conflicting files.
369177
370−##### Meta-strategies
371−
372−There's also a meta-strategy `%auto`, which is the most common.
373−If no strategy is supplied, then `%auto` is assumed. `%auto`
374−checks to see if Bob's desk exists, and if it doesn't we use a
375−`%init` merge. Otherwise, we progressively try `%fine`,
376−`%meet`, and `%mate` until one succeeds.
377−
378−If none succeed, we merge Bob's desk into a scratch desk. Then,
379−we merge Alice's desk into the scratch desk with the `%meld`
380−option to force the merge. For each file in the produced set of
381−conflicting files, we call the `++mash` function for the
382−appropriate mark, which annotates the conflicts if we know how.
383−
384−Finally, we display a message to the user informing them of the
385−scratch desk's existence, which files have annotated conflicts,
386−and which files have unannotated conflicts. When the user has
387−resolved the conflicts, they can merge the scratch desk back into
388−Bob's desk. This will be a `%fine` merge since Bob's head is in
389−the ancestry of the scratch desk.
390−
391−### Autosync
392−
393−Since `%clay` is reactive, it has a subscription interface.
394−Changes to the filesystem create events which code at Layers 3 or
395−4 (vanes or apps) can listen to.
396−
397−The `:hood` appliance uses subscriptions to implement "autosync".
398−When one desk is synced to another, any changes to the first desk
399−are automatically applied to the second -- for any two desks, on
400−any two urbits.
401−
402−Autosync isn't just mirroring. The target desk might have
403−changes of its own. We use the full merge capabilities of
404−`%clay` to try to make the merge clean. If there are conflicts,
405−it'll notify you through `:talk`, and ask you to resolve.
406−
407−There can be complex sync flows, many of which are useful.
408−Often, many urbits will be synced to some upstream desk that is
409−trusted to provide updates. Sometimes, it's useful to sync two
410−desks to each other, so that changes to one or the other are
411−mirrored. Cyclical sync structures are normal and healthy.
412−Also, one desk can be the target of multiple autosyncs.
178+`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it doesn't we use an `%init` merge. Otherwise, we progressively try `%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we merge Bob's desk into a scratch desk. Then, we merge Alice's desk into the scratch desk with the `%meld` option to force the merge.
179+
180+### Manipulation
181+
182+<h3 class="first child"><code>|rm path</code></h3>
183+
184+Remove the data at `path`. `path` must be a path to actual node, not a 'directory'
185+
186+### `|cp to from how`
187+
188+Copy the subtree `from` into the subtree `to`, committing it with
189+the specified merge strategy `how`.
190+
191+#### `|mv to from how`
192+
193+Move the subtree `from` into the subtree `to`, committing it with
194+the specified merge strategy `how`.
195+
196+In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The
197+`|rm` doesn't happen unless the `|cp` succeeds.
198+
199+### Generators
200+
201+<h3 class="first child"><code>+cat path</code> / <code>+cal [path ...]</code></h3>
202+
203+Similar to Unix `cat`. `+cat` takes a single `path`, `+cal` a list of paths.
204+
205+Produces the contents of the file at the given `path`.
206+
207+### `+ls path` / `+ll [path ...]`
208+
209+Similar to Unix `ls`. `+ls` takes a single `path`, `+ll` a list of paths.
210+
211+Produces a list of names at the `path`.