@@ -4,16 +4,13 @@ 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.
9−
107### Reading and Subscribing
118
129When reading from Clay, there are three types of requests. A
1310`%sing` request asks for data at single revsion. A `%next`
1411request asks to be notified the next time there's a change to
1512given file. A `%many` request asks to be notified on every
16−change in a desk for a range of changes.
13+change in a `desk` for a range of changes.
1714
1815For `%sing` and `%next`, there are generally three things to be
1916queried. A `%u` request simply checks for the existence of a
@@ -33,56 +30,66 @@ things in Urbit, aren't guaranteed to return immediately.
3330They'll return when they can, and they'll do so in a
3431referentially transparent manner.
3532
36−A `%next` request checks query at the given revision, and it
33+A `%next` request checks the query at the given revision, and it
3734produces the result of the query the next time it changes, along
38−with the revsion number when it changes. Thus, a `%next` of a
35+with the revision number when it changes. Thus, a `%next` of a
3936`%u` is triggered when a file is added or deleted, a `%next` of a
4037`%x` is triggered when a file is added, deleted, or changed, and
4138a `%next` of a `%y` is triggered when a file or any of its
4239children is added, deleted, or changed.
4340
44−A `%many` request is triggered every time the given desk has a
41+A `%many` request is triggered every time the given `desk` has a
4542new revision. Unlike a `%next`, a `%many` has both a start and
46−an end revsion, after which it stops returning. For `%next`, a
43+an end revision, after which it stops returning. For `%next`, a
4744single change is reported, and if the caller wishes to hear of
48−the next change, it must resubscribe. For `%many`, every revsion
45+the next change, it must resubscribe. For `%many`, every revision
4946from the start to the end triggers a response. Since a `%many`
5047request doesn't ask for any particular data, there aren't `%u`,
5148`%x`, and `%y` versions for it.
5249
53−For further information, see [Local Reads](@/docs/arvo/clay/local-reads.md),
54−[Local Subscriptions](@/docs/arvo/clay/local-sub.md), and [Foreign
55−Requests](@/docs/arvo/clay/foreign.md)
50+For further information, see [Local Reads](@/docs/arvo/Clay/local-reads.md),
51+[Local Subscriptions](@/docs/arvo/Clay/local-sub.md), and [Foreign
52+Requests](@/docs/arvo/Clay/foreign.md)
5653
5754### Unix sync
5855
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
56+Usage:
57+```
58+|mount %/path/to/directory %mount-point
59+|commit %mount-point
60+|autocommit %mount-point
61+```
62+
63+One of the primary functions of Clay is as a convenient user
64+interface. While tools exist to use Clay from within Urbit, it's
65+often useful to be able to treat Clay like any other filesystem
6266from the Unix perspective -- to "mount" it, as it were.
6367
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`.
68+From the dojo, you can run `|mount %/path/to/directory %mount-point`, and this
69+will mount the given Clay directory to the mount-point directory in Unix, with
70+your pier as the root directory. For example `|mount %/gen %generators` will
71+create a `/generators` directory in your pier, and mount the `/gen` folder at
72+that point. If you'd like to use the directory name as the mount point, you can
73+elide the last argument, e.g. `|mount %/gen` mounts `/gen` to `/gen`.
7074
71−### Merging
75+Every file is converted to `%mime` before it's written to Unix, and converted
76+back when read from Unix. The entire directory is watched (a la Dropbox), and
77+every change is committed once you run `|commit %mount-point`. Every change can
78+be automatically committed with `|autocommit %mount-point`.
7279
73−This section is up to date as of March 2021.
80+### Merging
7481
7582Usage:
7683```
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
84+|merge %destination-`desk` ~source-ship %source-`desk`
85+|merge %destination-`desk` ~source-ship %source-`desk`, =gem %strategy
86+|merge %destination-`desk` ~source-ship %source-`desk`, =cas ud+5
8087```
8188
8289Clay supports various merge strategies. A "commit" is a snapshot of
8390the files with a list of parents plus a date. Most commits have
8491one parent; a "merge" commit is a commit with two parents. The
85−%home desk starts with an initial commit with no parents; commits
92+%home `desk` starts with an initial commit with no parents; commits
8693with several parents ("octopus merges") are possible but we don't
8794generate them right now.
8895
@@ -90,12 +97,12 @@ Unless otherwise specified, all of the following create a new commit
9097with the source and destination commits as parents.
9198
9299Several strategies need a "merge-base". They find it by identifying
93−the most recent common ancestor of the two desks. If none, fail
100+the most recent common ancestor of the two `desk`s. If none, fail
94101with `%merge-no-merge-base`; if there are two or more, pick one.
95102
96103#### Strategies
97104
98−**`%init`**: the only way to create a desk. Not a true merge, since it
105+**`%init`**: the only way to create a `desk`. Not a true merge, since it
99106simply assigns the source commit to the destination.
100107
101108**`%fine`**: if source or destination are in the ancestry of each other,
@@ -117,42 +124,42 @@ allow intelligent merge of changes to different parts of a file.
117124file, use the version of the file in the merge-base.
118125
119126**`%only-this`**: create a merge commit with exactly the contents of the
120−destination desk.
127+destination `desk`.
121128
122129**`%only-that`**: create a merge commit with exactly the contents of the
123130source commit.
124131
125132**`%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.
133+destination `desk` except take any files from the source commit which
134+are not in the destination `desk`.
128135
129136**`%take-that`**: create a merge commit with exactly the contents of the
130−source commit except preserve any files from the destination desk
137+source commit except preserve any files from the destination `desk`
131138which are not in the source commit.
132139
133140**`%meet-this`**: merge as in `%meet`, except if both sides changed the same
134−file, use the version in the destination desk.
141+file, use the version in the destination `desk`.
135142
136143**`%meet-that`**: merge as in `%meet`, except if both sides changed the same
137144file, use the version in the source commit.
138145
139146#### Examples and notes:
140147
141−The most common merge strategy is %mate, which is a normal 3-way
148+The most common merge strategy is `%mate`, which is a normal 3-way
142149merge which aborts on conflict.
143150
144151`%take-that` is useful to "force" an OTA. After running `%take-that`,
145152you're guaranteed to have exactly the files in the source commit plus
146153any files you separately added.
147154
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
155+We speak of merging into a destination *`desk`* from a source *commit*
156+because while you can only merge on top of a `desk`, you can merge from
150157historical commits. For example,
151158```
152159|merge %old our %home, =cas ud+5, =gem %init
153160```
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
161+will create a new `desk` called `%old` with the 5th commit in `%home`.
162+You can revert the contents of a `desk` to what they were yesterday
156163with
157164```
158165|merge %home our %home, =cas da+(sub now ~d1), =gem %only-that
@@ -163,47 +170,52 @@ Note this is a normal `%only-that merge`, which means you're creating a
163170
164171`%meld` is rarely used on its own, however if you specify `%auto` or
165172omit the merge strategy, `%kiln` will run a `%meld` merge into a scratch
166−desk and then annotate the conflicts there.
173+`desk` and then annotate the conflicts there.
167174
168175If you resolve merge conflicts manually, for example by mounting the
169−desks, copying the files in Unix and then running `|commit`, you
176+`desk`s, copying the files in Unix and then running `|commit`, you
170177should 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
178+newly-fixed contents of your `desk`, but it will record that the merge
172179happened so that those conflicts don't reappear in later merges.
173180
174181If 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
182+merge two `desk`s which have no common ancestors. You need to give
176183them a common ancestor by choosing a merge strategy which doesn't
177184need a merge-base, like `%only-this`, `%only-that`, `%take-this`, or
178185`%take-that`.
179186
180187`%take-this` could be useful to install 3rd party software, but you
181188couldn't get subsequent updates this way, since the files would
182−already exist in the destination desk. Something like "take only
189+already exist in the destination `desk`. Something like "take only
183190the files which aren't in my OTA source or any other 3rd party app"
184191would be basically correct. This would require a parameter listing
185−the desks to not conflict with.
192+the `desk`s to not conflict with.
186193
187194`%meet-this` and `%meet-that` imply the existence of `%mate-this` and
188195`%mate-that`, but those don't exist yet.
189196
190197### Autosync
191198
192−Tracking and staying in sync with another desk is another
199+Usage:
200+```
201+|sync destination-desk ~source-ship source-desk
202+```
203+
204+Tracking and staying in sync with another `desk` is another
193205fundamental operation. We call this "autosync". This doesn't mean
194−simply mirroring a desk, since that wouldn't allow local changes.
206+simply mirroring a `desk`, since that wouldn't allow local changes.
195207We simply want to apply changes as they are made upstream, as
196208long as there are no conflicts with local changes.
197209
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.
210+This is implemented by subscribing to changes to the other `desk`, with a
211+`%many` request and, when it has changes, merging these changes into our `desk`
212+with the usual merge strategies.
201213
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
214+Note that it's quite reasonable for two `desk`s to be autosynced to
215+each other. This results in any change on one `desk` being mirrored
204216to the other and vice versa.
205217
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.
218+Additionally, it's fine to set up an autosync even if one `desk`,
219+the other `desk`, or both `desk`s do not exist. The sync will be
220+activated when the upstream `desk` comes into existence and will
221+create the downstream `desk` if needed.