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