@@ -25,325 +25,133 @@ a Unix directory. The Urbit process will watch this directory
25and automatically record edits as changes, Dropbox style. The
25and automatically record edits as changes, Dropbox style. The
26mounted directory is always at the root of your pier directory.
26mounted directory is always at the root of your pier directory.
28−## Commands
28+## Quickstart
30−Note that in both commands and generators, a currently unbound
30+Most of the time we want to use `%clay` from Unix.
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.
35−### Mounting to Unix
32+Mount the entire contents of your `home` desk to Unix:
37−#### `|mount [pax=path pot=$|(~ [knot ~])]`
34+ ~fintud-macrep:dojo>|mount %
39−Mount the path `pax` at the Unix mount point `pot`, the name of a
36+To explore the filesystem from inside Urbit `+ls` and `+cat` are useful:
40−subdirectory in your pier.
42− |mount %/pub/doc %documents
38+ ~fintud-macrep:dojo> +ls /=home=/web
44−with a `$PIER` of `/home/nixon/urbit/fintud-macrep`, will mount
40+Let's see the contents of `/=home=/web/md`:
45−`%/pub/doc` in `/home/nixon/urbit/fintud-macrep/documents`.
47−The mount point is optional; if it's not supplied, the last knot
42+ ~fintud-macrep:dojo> +cat /=home=/web/md
48−in the path (`%doc`) will be used.
50−#### `|unmount [mon=$|(term [knot path]) ~] `
44+Create a new desk:
52−Undo a mount, either by specifying the path or the mount point:
46+ |merge %sandbox ~fintud-macrep %sandbox
54− |unmount %/pub/doc
48+Sync it with a remote desk on the network:
57−It's a good habit to also delete the Unix subtree, but Urbit
50+ |sync %sandbox ~wactex-ribmex %examples
58−doesn't do it for you.
60−### Revision-control operations
52+## Manual
62−#### `|merge [syd=desk src=beak how=$|(~ [germ ~])]`
54+<h3 class="first child">Paths</h3>
64−Merge the beak `src` into the desk `syd`, with optional merge
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`.
67−The `src` beak can be a desk (`%home`); a plot-desk cell
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`.
68−(`[~doznec %home]`); or a plot-desk-case path (`/=home=`).
70− |merge %home-work /=home= %fine
60+#### Relative paths
71− |merge %home-work /=home=
73−#### `|sync [syd=desk her=plot org=$|(~ [desk ~])]`
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`:
78− |sync %home-local ~doznec %home
81−Note that `|merge` takes a path because it needs a source case
82−(revision), which would make no sense for `|sync`.
84−#### `|label [syd=desk lab=term]`
86−Label the current version of desk `syd`:
88−#### `|unsync [syd=desk her=plot org=desk ~]`
90−Turn off autosync. The argument needs to match the original
91−`|sync` perfectly, or Urbit will become angry and confused.
93−### Filesystem manipulation
95−#### `|rm [paz=(list path)]`
97−Remove any leaf at each of the paths in `paz`.
99− |rm /===/pub/fab/nixon/hoon
101−Remember that folders in `%clay` are a consequence of the tree of
102−leaves; there is no `rmdir` or `mkdir`.
104−#### `|cp [too=path fro=path how=$|(~ [germ ~])]`
106−Copy the subtree `fro` into the subtree `too`, committing it with
107−the specified merge strategy.
109−#### `|mv [too=path fro=path how=$|(~ [germ ~])]`
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.
115−### Filesystem generators
117−#### `+cal [paz=(list path)]`
118−#### `+cat [pax=path]`
120−Produce the noun, if any, at each of these (global) paths.
121−`+cat` produces one result, `+cal` a list.
123−#### `+ls [pax=path ~]`
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`.
127−Because generators aren't passed the dojo's default path, unlike
64+#### Substitution
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 %`.
132−#### `+ll [pax=path ~]`
66+If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`,
133−
67+and `/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of
134−Like `+ls`, but the result is a list of full paths. Useful as
68+`/=/=/zoo` or `/=/=/=/voo`, write `/==zoo` or `/===voo`.
135−Urbit equivalent of the Unix wildcard `*`.
139−As a noun, a path in `%clay` is a `(list knot)`, where each
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`.
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, `~`.
144−As an ordinary Hoon noun, `[%foo %bar %baz]` has this structure.
72+### Revision-control
145−But Hoon also supports the Unix path syntax: `/foo/bar/baz` is
148−### Relative paths
74+<h3 class="first child"><code>|mount clay-path [unix-name]</code></h3>
150−The Hoon path syntax is always defined relative to a default
76+Mount the `clay-path` at the unix mount point `unix-name`.
151−path, which is configuration state in the Hoon parser. In
152−`:dojo`, this works a little like the Unix current directory.
154−(But note that in Unix, relative paths are expanded by the
78+**Examples:**
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
161−Relative path syntax: `%` is the default path (Unix `.`). `%%`
80+ |mount %/web
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`.
167−Unix has no top-level substitution syntax, but Urbit does. If
82+Mounts `%/web` to `/web` inside your pier directory.
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.
173−### Beak
84+ |mount %/gen generators
175−The top three knots in a `%clay` path are `/plot/desk/case`,
86+Mounts `%/gen` to `/generators` inside your pier directory.
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`.
181−### Spur
88+### `|unmount [clay-path || unix-name]`
183−The rest of the path, or `spur`, navigates a tree of `node`
90+Unmount the path or name from Unix.
184−nouns. A `node` is like an inode in a Unix filesystem, but
187−An inode is *either* a file or a directory. A `node` is *both* a
92+**Examples:**
188−folder (which may be empty) and an optional leaf (a noun).
190−There is no `rmdir` or `mkdir`; an empty node is automatically
94+ |unmount %/web
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.
195−### Leaf
96+Unmounts the path `%/web` from whatever name it was mounted as.
197−`%clay` is a typed filesystem, or more precisely a *marked* one.
98+ |unmount %generators
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)
202−The mark name is actually the last knot in the path. Or to put
100+Unmounts the Unix path `/generators`.
203−it differently: if any `%clay` node has a leaf, its name within
204−its parent is its mark.
206−This is ridiculously confusing without examples. Suppose we have
102+### `|merge desk beak [strategy]`
207−the following Unix files, with directories to match:
209− doc.md
104+Merges a `beak` into a `desk` using an optional merge `strategy`.
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`)
215− %/doc/md
108+**Examples:**
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
224−Perhaps this example helps explains *why* `%clay` uses this node
110+ |merge %home-work /=home= %fine
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`.
230−And three, the `%clay` node structure syncs invertibly with an
112+Merge `/=home=` into `%home-work` using merge strategy `%fine`.
231−equivalent, and not unduly weird, Unix inode layout.
233−### Mounting to Unix
114+ |merge %examples [~wacbex-ribmex %examples]
235−The most convenient way of interacting with `%clay` is mounting
116+Merge the `%examples` desk from `~waxbex-ribmex`
236−it to Unix, and modifying it with Unix tools. The mount
237−directory is a flat subdirectory of your Urbit pier.
239−When you have a live mount point, Urbit monitors it with
118+### `|sync desk plot [plot-desk]`
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.
244−Unix files beginning with `.`, with no extension, with an
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`.
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.
250−### More about desks and marks
122+**Examples:**
252−The Hoon source code for a mark like `%md` is in
124+ |sync %home-local ~doznec %home
253−`/===/mar/md/hoon`. But relative to what beak? What's in the
125+ |sync %home ~doznec
256−The mark source of a leaf in `%clay` is always relative to its
127+### `|unsync desk plot [plot-desk]`
257−own plot, desk and case. For example, a leaf at
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.
261−is controlled by the mark source
131+Example:
263− `/~fintud-macrep/home/31/mar/md/hoon`
133+ |unsync %home-local ~doznec %home
265−If there is no such file or it doesn't compile, the mark is
135+### `|label desk name`
266−effectively treated as `%noun`, ie, an arbitrary value.
268−(Note that when updating a mark, any update which shrinks the set
137+Label the current version of `desk` `name`.
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.)
273−What can you do with a mark? Validate an arbitrary noun; perform
139+Example:
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.
278−Marks are also used to describe network messages. In this case,
141+ |label %home release
279−the mark source beak is the beak of the receiving urbit.
281−### Desks and merging
283−As in any git-shaped revision control system, the core operation
144+### Merge strategies
284−of the system is merging.
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`.
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
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.
305−#### Merge strategies
307−There are seven different merge strategies. Throughout our
308−discussion, we'll say that the merge is from Alice's desk to
311−##### Direct strategies
313−A `%init` merge should be used iff it's the first commit to a
146+`%init` - Used iff it's the first commit to a desk.
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.
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.
327−A `%that` merge means to take what's in Alice's desk, but join
148+`%this` - Keep what's in Bob's desk, but join the ancestry.
328−the ancestry. This is the reverse of `%this`.
330−A `%fine` merge is a "fast-forward" merge. This succeeds iff one
150+`%that` - take what's in Alice's desk, but join the ancestry. This is the reverse of `%this`.
331−head is in the ancestry of the other. In this case, we use the
332−descendant as our new head.
334−For `%meet`, `%mate`, and `%meld` merges, we first find the most
152+`%fine` - "fast-forward" merge. This succeeds iff one head is in the ancestry of the other.
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.
342−There's a functional inclusion ordering on `%fine`, `%meet`,
154+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to use as our merge base.
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.
348A `%meet` merge only succeeds if the changes from the merge base
156A `%meet` merge only succeeds if the changes from the merge base
349to Alice's head (hereafter, "Alice's changes") are in different
157to 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
367changed files plus the successfully merged files plus the merge
175changed files plus the successfully merged files plus the merge
368base's version of the conflicting files.
176base's version of the conflicting files.
370−##### Meta-strategies
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.
372−There's also a meta-strategy `%auto`, which is the most common.
180+### Manipulation
373−If no strategy is supplied, then `%auto` is assumed. `%auto`
181+
374−checks to see if Bob's desk exists, and if it doesn't we use a
182+<h3 class="first child"><code>|rm path</code></h3>
375−`%init` merge. Otherwise, we progressively try `%fine`,
183+
376−`%meet`, and `%mate` until one succeeds.
184+Remove the data at `path`. `path` must be a path to actual node, not a 'directory'
378−If none succeed, we merge Bob's desk into a scratch desk. Then,
186+### `|cp to from how`
379−we merge Alice's desk into the scratch desk with the `%meld`
187+
380−option to force the merge. For each file in the produced set of
188+Copy the subtree `from` into the subtree `to`, committing it with
381−conflicting files, we call the `++mash` function for the
189+the specified merge strategy `how`.
382−appropriate mark, which annotates the conflicts if we know how.
190+
383−
191+#### `|mv to from how`
384−Finally, we display a message to the user informing them of the
192+
385−scratch desk's existence, which files have annotated conflicts,
193+Move the subtree `from` into the subtree `to`, committing it with
386−and which files have unannotated conflicts. When the user has
194+the specified merge strategy `how`.
387−resolved the conflicts, they can merge the scratch desk back into
195+
388−Bob's desk. This will be a `%fine` merge since Bob's head is in
196+In `%clay`, `|mv` is just a shorthand for `|cp` then `|rm`. The
389−the ancestry of the scratch desk.
197+`|rm` doesn't happen unless the `|cp` succeeds.
391−### Autosync
199+### Generators
393−Since `%clay` is reactive, it has a subscription interface.
201+<h3 class="first child"><code>+cat path</code> / <code>+cal [path ...]</code></h3>
394−Changes to the filesystem create events which code at Layers 3 or
202+
395−4 (vanes or apps) can listen to.
203+Similar to Unix `cat`. `+cat` takes a single `path`, `+cal` a list of paths.
397−The `:hood` appliance uses subscriptions to implement "autosync".
205+Produces the contents of the file at the given `path`.
398−When one desk is synced to another, any changes to the first desk
206+
399−are automatically applied to the second -- for any two desks, on
207+### `+ls path` / `+ll [path ...]`
401−
209+Similar to Unix `ls`. `+ls` takes a single `path`, `+ll` a list of paths.
402−Autosync isn't just mirroring. The target desk might have
210+
403−changes of its own. We use the full merge capabilities of
211+Produces a list of names at the `path`.
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.
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.