@@ -4,16 +4,13 @@ weight = 3
4template = "doc.html"
4template = "doc.html"
7−This document covers common uses of Clay for developers. Some parts of it may be
8−out of date as of March 2021.
10### Reading and Subscribing
7### Reading and Subscribing
12When reading from Clay, there are three types of requests. A
9When reading from Clay, there are three types of requests. A
13`%sing` request asks for data at single revsion. A `%next`
10`%sing` request asks for data at single revsion. A `%next`
14request asks to be notified the next time there's a change to
11request asks to be notified the next time there's a change to
15given file. A `%many` request asks to be notified on every
12given 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.
18For `%sing` and `%next`, there are generally three things to be
15For `%sing` and `%next`, there are generally three things to be
19queried. A `%u` request simply checks for the existence of a
16queried. A `%u` request simply checks for the existence of a
@@ -33,56 +30,66 @@ things in Urbit, aren't guaranteed to return immediately.
33They'll return when they can, and they'll do so in a
30They'll return when they can, and they'll do so in a
34referentially transparent manner.
31referentially transparent manner.
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
37produces the result of the query the next time it changes, along
34produces 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
39`%u` is triggered when a file is added or deleted, a `%next` of a
36`%u` is triggered when a file is added or deleted, a `%next` of a
40`%x` is triggered when a file is added, deleted, or changed, and
37`%x` is triggered when a file is added, deleted, or changed, and
41a `%next` of a `%y` is triggered when a file or any of its
38a `%next` of a `%y` is triggered when a file or any of its
42children is added, deleted, or changed.
39children is added, deleted, or changed.
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
45new revision. Unlike a `%next`, a `%many` has both a start and
42new 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
47single change is reported, and if the caller wishes to hear of
44single 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
49from the start to the end triggers a response. Since a `%many`
46from the start to the end triggers a response. Since a `%many`
50request doesn't ask for any particular data, there aren't `%u`,
47request doesn't ask for any particular data, there aren't `%u`,
51`%x`, and `%y` versions for it.
48`%x`, and `%y` versions for it.
53−For further information, see [Local Reads](@/docs/arvo/clay/local-reads.md),
50+For further information, see [Local Reads](@/docs/arvo/Clay/local-reads.md),
54−[Local Subscriptions](@/docs/arvo/clay/local-sub.md), and [Foreign
51+[Local Subscriptions](@/docs/arvo/Clay/local-sub.md), and [Foreign
55−Requests](@/docs/arvo/clay/foreign.md)
52+Requests](@/docs/arvo/Clay/foreign.md)
57### Unix sync
54### Unix sync
58+|mount %/path/to/directory %mount-point
60+|autocommit %mount-point
59−One of the primary functions of clay is as a convenient user
63+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
64+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
65+often useful to be able to treat Clay like any other filesystem
62from the Unix perspective -- to "mount" it, as it were.
66from the Unix perspective -- to "mount" it, as it were.
64−From urbit, you can run `|mount /path/to/directory %mount-point`,
68+From the dojo, you can run `|mount %/path/to/directory %mount-point`, and this
65−and this will mount the given clay directory to the mount-point
69+will mount the given Clay directory to the mount-point directory in Unix, with
66−directory in Unix. Every file is converted to `%mime` before it's
70+your pier as the root directory. For example `|mount %/gen %generators` will
67−written to Unix, and converted back when read from Unix. The
71+create a `/generators` directory in your pier, and mount the `/gen` folder at
68−entire directory is watched (a la Dropbox), and every change is
72+that point. If you'd like to use the directory name as the mount point, you can
69−committed once you run `|commit %mount-point`.
73+elide the last argument, e.g. `|mount %/gen` mounts `/gen` to `/gen`.
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`.
73−This section is up to date as of March 2021.
80+### Merging
77−|merge %destination-desk ~source-ship %source-desk
84+|merge %destination-`desk` ~source-ship %source-`desk`
78−|merge %destination-desk ~source-ship %source-desk, =gem %strategy
85+|merge %destination-`desk` ~source-ship %source-`desk`, =gem %strategy
79−|merge %destination-desk ~source-ship %source-desk, =cas ud+5
86+|merge %destination-`desk` ~source-ship %source-`desk`, =cas ud+5
82Clay supports various merge strategies. A "commit" is a snapshot of
89Clay supports various merge strategies. A "commit" is a snapshot of
83the files with a list of parents plus a date. Most commits have
90the files with a list of parents plus a date. Most commits have
84one parent; a "merge" commit is a commit with two parents. The
91one 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
86with several parents ("octopus merges") are possible but we don't
93with several parents ("octopus merges") are possible but we don't
87generate them right now.
94generate them right now.
@@ -90,12 +97,12 @@ Unless otherwise specified, all of the following create a new commit
90with the source and destination commits as parents.
97with the source and destination commits as parents.
92Several strategies need a "merge-base". They find it by identifying
99Several 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
94with `%merge-no-merge-base`; if there are two or more, pick one.
101with `%merge-no-merge-base`; if there are two or more, pick one.
96#### Strategies
103#### Strategies
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
99simply assigns the source commit to the destination.
106simply assigns the source commit to the destination.
101**`%fine`**: if source or destination are in the ancestry of each other,
108**`%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.
117file, use the version of the file in the merge-base.
124file, use the version of the file in the merge-base.
119**`%only-this`**: create a merge commit with exactly the contents of the
126**`%only-this`**: create a merge commit with exactly the contents of the
120−destination desk.
127+destination `desk`.
122**`%only-that`**: create a merge commit with exactly the contents of the
129**`%only-that`**: create a merge commit with exactly the contents of the
123source commit.
130source commit.
125**`%take-this`**: create a merge commit with exactly the contents of the
132**`%take-this`**: create a merge commit with exactly the contents of the
126−destination desk except take any files from the source commit which
133+destination `desk` except take any files from the source commit which
127−are not in the destination desk.
134+are not in the destination `desk`.
129**`%take-that`**: create a merge commit with exactly the contents of the
136**`%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`
131which are not in the source commit.
138which are not in the source commit.
133**`%meet-this`**: merge as in `%meet`, except if both sides changed the same
140**`%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`.
136**`%meet-that`**: merge as in `%meet`, except if both sides changed the same
143**`%meet-that`**: merge as in `%meet`, except if both sides changed the same
137file, use the version in the source commit.
144file, use the version in the source commit.
139#### Examples and notes:
146#### Examples and notes:
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
142merge which aborts on conflict.
149merge which aborts on conflict.
144`%take-that` is useful to "force" an OTA. After running `%take-that`,
151`%take-that` is useful to "force" an OTA. After running `%take-that`,
145you're guaranteed to have exactly the files in the source commit plus
152you're guaranteed to have exactly the files in the source commit plus
146any files you separately added.
153any files you separately added.
148−We speak of merging into a destination *desk* from a source *commit*
155+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
156+because while you can only merge on top of a `desk`, you can merge from
150historical commits. For example,
157historical commits. For example,
152|merge %old our %home, =cas ud+5, =gem %init
159|merge %old our %home, =cas ud+5, =gem %init
154−will create a new desk called `%old` with the 5th commit in `%home`.
161+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
162+You can revert the contents of a `desk` to what they were yesterday
158|merge %home our %home, =cas da+(sub now ~d1), =gem %only-that
165|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
164`%meld` is rarely used on its own, however if you specify `%auto` or
171`%meld` is rarely used on its own, however if you specify `%auto` or
165omit the merge strategy, `%kiln` will run a `%meld` merge into a scratch
172omit 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.
168If you resolve merge conflicts manually, for example by mounting the
175If 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
170should usually run an `%only-this merge`. This will not change the
177should 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
172happened so that those conflicts don't reappear in later merges.
179happened so that those conflicts don't reappear in later merges.
174If you get a `%merge-no-merge-base` error, this means you're trying to
181If 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
176them a common ancestor by choosing a merge strategy which doesn't
183them a common ancestor by choosing a merge strategy which doesn't
177need a merge-base, like `%only-this`, `%only-that`, `%take-this`, or
184need a merge-base, like `%only-this`, `%only-that`, `%take-this`, or
178`%take-that`.
185`%take-that`.
180`%take-this` could be useful to install 3rd party software, but you
187`%take-this` could be useful to install 3rd party software, but you
181couldn't get subsequent updates this way, since the files would
188couldn'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
183the files which aren't in my OTA source or any other 3rd party app"
190the files which aren't in my OTA source or any other 3rd party app"
184would be basically correct. This would require a parameter listing
191would be basically correct. This would require a parameter listing
185−the desks to not conflict with.
192+the `desk`s to not conflict with.
187`%meet-this` and `%meet-that` imply the existence of `%mate-this` and
194`%meet-this` and `%meet-that` imply the existence of `%mate-this` and
188`%mate-that`, but those don't exist yet.
195`%mate-that`, but those don't exist yet.
190### Autosync
197### Autosync
201+|sync destination-desk ~source-ship source-desk
192−Tracking and staying in sync with another desk is another
204+Tracking and staying in sync with another `desk` is another
193fundamental operation. We call this "autosync". This doesn't mean
205fundamental 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.
195We simply want to apply changes as they are made upstream, as
207We simply want to apply changes as they are made upstream, as
196long as there are no conflicts with local changes.
208long as there are no conflicts with local changes.
198−This is implemented by watching the other desk, and, when it has
210+This is implemented by subscribing to changes to the other `desk`, with a
199−changes, merging these changes into our desk with the usual merge
211+`%many` request and, when it has changes, merging these changes into our `desk`
200−strategies.
212+with the usual merge strategies.
202−Note that it's quite reasonable for two desks to be autosynced to
214+Note that it's quite reasonable for two `desk`s to be autosynced to
203−each other. This results in any change on one desk being mirrored
215+each other. This results in any change on one `desk` being mirrored
204to the other and vice versa.
216to the other and vice versa.
206−Additionally, it's fine to set up an autosync even if one desk,
218+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
219+the other `desk`, or both `desk`s do not exist. The sync will be
208−activated when the upstream desk comes into existence and will
220+activated when the upstream `desk` comes into existence and will
209−create the downstream desk if needed.
221+create the downstream `desk` if needed.