@@ -4,8 +4,7 @@ weight = 3
44template = "doc.html"
55+++
66
7−This document covers common uses of Clay for developers. Some parts of it may be
8−out of date as of March 2021.
7+This document is up-to-date as of March 2021.
98
109### Reading and Subscribing
1110
@@ -13,7 +12,7 @@ When reading from Clay, there are three types of requests. A
1312`%sing` request asks for data at single revsion. A `%next`
1413request asks to be notified the next time there's a change to
1514given file. A `%many` request asks to be notified on every
16−change in a desk for a range of changes.
15+change in a `desk` for a range of changes.
1716
1817For `%sing` and `%next`, there are generally three things to be
1918queried. A `%u` request simply checks for the existence of a
@@ -33,19 +32,19 @@ things in Urbit, aren't guaranteed to return immediately.
3332They'll return when they can, and they'll do so in a
3433referentially transparent manner.
3534
36−A `%next` request checks query at the given revision, and it
35+A `%next` request checks the query at the given revision, and it
3736produces the result of the query the next time it changes, along
38−with the revsion number when it changes. Thus, a `%next` of a
37+with the revision number when it changes. Thus, a `%next` of a
3938`%u` is triggered when a file is added or deleted, a `%next` of a
4039`%x` is triggered when a file is added, deleted, or changed, and
4140a `%next` of a `%y` is triggered when a file or any of its
4241children is added, deleted, or changed.
4342
44−A `%many` request is triggered every time the given desk has a
43+A `%many` request is triggered every time the given `desk` has a
4544new revision. Unlike a `%next`, a `%many` has both a start and
46−an end revsion, after which it stops returning. For `%next`, a
45+an end revision, after which it stops returning. For `%next`, a
4746single change is reported, and if the caller wishes to hear of
48−the next change, it must resubscribe. For `%many`, every revsion
47+the next change, it must resubscribe. For `%many`, every revision
4948from the start to the end triggers a response. Since a `%many`
5049request doesn't ask for any particular data, there aren't `%u`,
5150`%x`, and `%y` versions for it.
@@ -56,33 +55,43 @@ Requests](@/docs/arvo/clay/foreign.md)
5655
5756### Unix sync
5857
59−One of the primary functions of clay is as a convenient user
60−interface. While tools exist to use clay from within urbit, it's
61−often useful to be able to treat clay like any other filesystem
58+Usage:
59+```
60+|mount %/path/to/directory %mount-point
61+|commit %mount-point
62+|autocommit %mount-point
63+```
64+
65+One of the primary functions of Clay is as a convenient user
66+interface. While tools exist to use Clay from within Urbit, it's
67+often useful to be able to treat Clay like any other filesystem
6268from the Unix perspective -- to "mount" it, as it were.
6369
64−From urbit, you can run `|mount /path/to/directory %mount-point`,
65−and this will mount the given clay directory to the mount-point
66−directory in Unix. Every file is converted to `%mime` before it's
67−written to Unix, and converted back when read from Unix. The
68−entire directory is watched (a la Dropbox), and every change is
69−committed once you run `|commit %mount-point`.
70+From the dojo, you can run `|mount %/path/to/directory %mount-point`, and this
71+will mount the given Clay directory to the mount-point directory in Unix, with
72+your pier as the root directory. For example `|mount %/gen %generators` will
73+create a `/generators` directory in your pier, and mount the `/gen` folder at
74+that point. If you'd like to use the directory name as the mount point, you can
75+elide the last argument, e.g. `|mount %/gen` mounts `/gen` to `/gen`.
7076
71−### Merging
77+Every file is converted to `%mime` before it's written to Unix, and converted
78+back when read from Unix. The entire directory is watched (a la Dropbox), and
79+every change is committed once you run `|commit %mount-point`. Every change can
80+be automatically committed with `|autocommit %mount-point`.
7281
73−This section is up to date as of March 2021.
82+### Merging
7483
7584Usage:
7685```
77−|merge %destination-desk ~source-ship %source-desk
78−|merge %destination-desk ~source-ship %source-desk, =gem %strategy
79−|merge %destination-desk ~source-ship %source-desk, =cas ud+5
86+|merge %target-desk ~source-ship %source-desk
87+|merge %target-desk ~source-ship %source-desk, =gem %strategy
88+|merge %target-desk ~source-ship %source-desk, =cas ud+5
8089```
8190
8291Clay supports various merge strategies. A "commit" is a snapshot of
8392the files with a list of parents plus a date. Most commits have
8493one parent; a "merge" commit is a commit with two parents. The
85−%home desk starts with an initial commit with no parents; commits
94+%home `desk` starts with an initial commit with no parents; commits
8695with several parents ("octopus merges") are possible but we don't
8796generate them right now.
8897
@@ -90,12 +99,12 @@ Unless otherwise specified, all of the following create a new commit
9099with the source and destination commits as parents.
91100
92101Several strategies need a "merge-base". They find it by identifying
93−the most recent common ancestor of the two desks. If none, fail
102+the most recent common ancestor of the two `desk`s. If none, fail
94103with `%merge-no-merge-base`; if there are two or more, pick one.
95104
96105#### Strategies
97106
98−**`%init`**: the only way to create a desk. Not a true merge, since it
107+**`%init`**: the only way to create a `desk`. Not a true merge, since it
99108simply assigns the source commit to the destination.
100109
101110**`%fine`**: if source or destination are in the ancestry of each other,
@@ -117,42 +126,42 @@ allow intelligent merge of changes to different parts of a file.
117126file, use the version of the file in the merge-base.
118127
119128**`%only-this`**: create a merge commit with exactly the contents of the
120−destination desk.
129+destination `desk`.
121130
122131**`%only-that`**: create a merge commit with exactly the contents of the
123132source commit.
124133
125134**`%take-this`**: create a merge commit with exactly the contents of the
126−destination desk except take any files from the source commit which
127−are not in the destination desk.
135+destination `desk` except take any files from the source commit which
136+are not in the destination `desk`.
128137
129138**`%take-that`**: create a merge commit with exactly the contents of the
130−source commit except preserve any files from the destination desk
139+source commit except preserve any files from the destination `desk`
131140which are not in the source commit.
132141
133142**`%meet-this`**: merge as in `%meet`, except if both sides changed the same
134−file, use the version in the destination desk.
143+file, use the version in the destination `desk`.
135144
136145**`%meet-that`**: merge as in `%meet`, except if both sides changed the same
137146file, use the version in the source commit.
138147
139148#### Examples and notes:
140149
141−The most common merge strategy is %mate, which is a normal 3-way
150+The most common merge strategy is `%mate`, which is a normal 3-way
142151merge which aborts on conflict.
143152
144153`%take-that` is useful to "force" an OTA. After running `%take-that`,
145154you're guaranteed to have exactly the files in the source commit plus
146155any files you separately added.
147156
148−We speak of merging into a destination *desk* from a source *commit*
149−because while you can only merge on top of a desk, you can merge from
157+We speak of merging into a destination *`desk`* from a source *commit*
158+because while you can only merge on top of a `desk`, you can merge from
150159historical commits. For example,
151160```
152161|merge %old our %home, =cas ud+5, =gem %init
153162```
154−will create a new desk called `%old` with the 5th commit in `%home`.
155−You can revert the contents of a desk to what they were yesterday
163+will create a new `desk` called `%old` with the 5th commit in `%home`.
164+You can revert the contents of a `desk` to what they were yesterday
156165with
157166```
158167|merge %home our %home, =cas da+(sub now ~d1), =gem %only-that
@@ -163,47 +172,52 @@ Note this is a normal `%only-that merge`, which means you're creating a
163172
164173`%meld` is rarely used on its own, however if you specify `%auto` or
165174omit the merge strategy, `%kiln` will run a `%meld` merge into a scratch
166−desk and then annotate the conflicts there.
175+`desk` and then annotate the conflicts there.
167176
168177If you resolve merge conflicts manually, for example by mounting the
169−desks, copying the files in Unix and then running `|commit`, you
178+`desk`s, copying the files in Unix and then running `|commit`, you
170179should usually run an `%only-this merge`. This will not change the
171−newly-fixed contents of your desk, but it will record that the merge
180+newly-fixed contents of your `desk`, but it will record that the merge
172181happened so that those conflicts don't reappear in later merges.
173182
174183If you get a `%merge-no-merge-base` error, this means you're trying to
175−merge two desks which have no common ancestors. You need to give
184+merge two `desk`s which have no common ancestors. You need to give
176185them a common ancestor by choosing a merge strategy which doesn't
177186need a merge-base, like `%only-this`, `%only-that`, `%take-this`, or
178187`%take-that`.
179188
180189`%take-this` could be useful to install 3rd party software, but you
181190couldn't get subsequent updates this way, since the files would
182−already exist in the destination desk. Something like "take only
191+already exist in the destination `desk`. Something like "take only
183192the files which aren't in my OTA source or any other 3rd party app"
184193would be basically correct. This would require a parameter listing
185−the desks to not conflict with.
194+the `desk`s to not conflict with.
186195
187196`%meet-this` and `%meet-that` imply the existence of `%mate-this` and
188197`%mate-that`, but those don't exist yet.
189198
190199### Autosync
191200
192−Tracking and staying in sync with another desk is another
201+Usage:
202+```
203+|sync %target-desk ~source-ship %source-desk
204+```
205+
206+Tracking and staying in sync with another `desk` is another
193207fundamental operation. We call this "autosync". This doesn't mean
194−simply mirroring a desk, since that wouldn't allow local changes.
208+simply mirroring a `desk`, since that wouldn't allow local changes.
195209We simply want to apply changes as they are made upstream, as
196210long as there are no conflicts with local changes.
197211
198−This is implemented by watching the other desk, and, when it has
199−changes, merging these changes into our desk with the usual merge
200−strategies.
212+This is implemented by subscribing to changes to the other `desk`, with a
213+`%many` request and, when it has changes, merging these changes into our `desk`
214+with the usual merge strategies.
201215
202−Note that it's quite reasonable for two desks to be autosynced to
203−each other. This results in any change on one desk being mirrored
216+Note that it's quite reasonable for two `desk`s to be autosynced to
217+each other. This results in any change on one `desk` being mirrored
204218to the other and vice versa.
205219
206−Additionally, it's fine to set up an autosync even if one desk,
207−the other desk, or both desks do not exist. The sync will be
208−activated when the upstream desk comes into existence and will
209−create the downstream desk if needed.
220+Additionally, it's fine to set up an autosync even if one `desk`,
221+the other `desk`, or both `desk`s do not exist. The sync will be
222+activated when the upstream `desk` comes into existence and will
223+create the downstream `desk` if needed.