@@ -6,50 +6,51 @@ template = "doc.html"
66
77### Reading and Subscribing
88
9−When reading from Clay, there are three types of requests. A
10−`%sing` request asks for data at single revsion. A `%next`
9+When reading from Clay, there are three types of requests. A
10+`%sing` request asks for data at single revsion. A `%next`
1111request asks to be notified the next time there's a change to
12−given file. A `%many` request asks to be notified on every
12+given file. A `%many` request asks to be notified on every
1313change in a `desk` for a range of changes.
1414
1515For `%sing` and `%next`, there are generally three things to be
16−queried. A `%u` request simply checks for the existence of a
17−file at a path. A `%x` request gets the data in the file at a
18−path. A `%y` request gets a hash of the data in the file at the
19−path combined with all its children and their data. Thus, `%y`
16+queried. A `%u` request simply checks for the existence of a
17+file at a path. A `%x` request gets the data in the file at a
18+path. A `%y` request gets a hash of the data in the file at the
19+path combined with all its children and their data. Thus, `%y`
2020of a node changes if it or any of its children change.
2121
22−A `%sing` request is fulfilled immediately if possible. If the
22+A `%sing` request is fulfilled immediately if possible. If the
2323requested revision is in the future, or is on another ship for
2424which we don't have the result cached, we don't respond
25−immediately. If the requested revision is in the future, we wait
26−until the revision happens before we respond to the request. If
25+immediately. If the requested revision is in the future, we wait
26+until the revision happens before we respond to the request. If
2727the request is for data on another ship, we pass on the request
28−to the other ship. In general, Clay subscriptions, like most
28+to the other ship. In general, Clay subscriptions, like most
2929things in Urbit, aren't guaranteed to return immediately.
3030They'll return when they can, and they'll do so in a
3131referentially transparent manner.
3232
3333A `%next` request checks the query at the given revision, and it
3434produces the result of the query the next time it changes, along
35−with the revision number when it changes. Thus, a `%next` of a
35+with the revision number when it changes. Thus, a `%next` of a
3636`%u` is triggered when a file is added or deleted, a `%next` of a
3737`%x` is triggered when a file is added, deleted, or changed, and
3838a `%next` of a `%y` is triggered when a file or any of its
3939children is added, deleted, or changed.
4040
4141A `%many` request is triggered every time the given `desk` has a
42−new revision. Unlike a `%next`, a `%many` has both a start and
43−an end revision, after which it stops returning. For `%next`, a
42+new revision. Unlike a `%next`, a `%many` has both a start and
43+an end revision, after which it stops returning. For `%next`, a
4444single change is reported, and if the caller wishes to hear of
45−the next change, it must resubscribe. For `%many`, every revision
46−from the start to the end triggers a response. Since a `%many`
45+the next change, it must resubscribe. For `%many`, every revision
46+from the start to the end triggers a response. Since a `%many`
4747request doesn't ask for any particular data, there aren't `%u`,
4848`%x`, and `%y` versions for it.
4949
5050### Unix sync
5151
5252Usage:
53+
5354```
5455|mount %/path/to/directory %mount-point
5556|commit %mount-point
@@ -76,123 +77,128 @@ be automatically committed with `|autocommit %mount-point`.
7677### Merging
7778
7879Usage:
80+
7981```
8082|merge %target-desk ~source-ship %source-desk
8183|merge %target-desk ~source-ship %source-desk, =gem %strategy
8284|merge %target-desk ~source-ship %source-desk, =cas ud+5
8385```
8486
85−Clay supports various merge strategies. A "commit" is a snapshot of
86−the files with a list of parents plus a date. Most commits have
87−one parent; a "merge" commit is a commit with two parents. The
88−%home `desk` starts with an initial commit with no parents; commits
87+Clay supports various merge strategies. A "commit" is a snapshot of
88+the files with a list of parents plus a date. Most commits have
89+one parent; a "merge" commit is a commit with two parents. The
90+`%base` `desk` starts with an initial commit with no parents; commits
8991with several parents ("octopus merges") are possible but we don't
9092generate them right now.
91−
93+
9294Unless otherwise specified, all of the following create a new commit
9395with the source and destination commits as parents.
94−
95−Several strategies need a "merge-base". They find it by identifying
96−the most recent common ancestor of the two `desk`s. If none, fail
96+
97+Several strategies need a "merge-base". They find it by identifying
98+the most recent common ancestor of the two `desk`s. If none, fail
9799with `%merge-no-merge-base`; if there are two or more, pick one.
98100
99101#### Strategies
100−
101−**`%init`**: the only way to create a `desk`. Not a true merge, since it
102+
103+**`%init`**: the only way to create a `desk`. Not a true merge, since it
102104simply assigns the source commit to the destination.
103−
105+
104106**`%fine`**: if source or destination are in the ancestry of each other,
105−use the newer one; else abort. If the destination is ahead of the
106−source, succeed but do nothing. If the source is ahead of the
107+use the newer one; else abort. If the destination is ahead of the
108+source, succeed but do nothing. If the source is ahead of the
107109destination, assign the next revision number to the source commit.
108110Some call this "fast-forward".
109−
111+
110112**`%meet`**: combine changes, failing if both sides changed the same file.
111113Specifically, take diff(merge-base,source) and
112114diff(merge-base,destination) and combine them as long as those diffs
113115touch different files.
114−
116+
115117**`%mate`**: combine changes, failing if both sides changed the same part
116−of a file. Identical to `%meet`, except that some marks, like `%hoon`,
118+of a file. Identical to `%meet`, except that some marks, like `%hoon`,
117119allow intelligent merge of changes to different parts of a file.
118−
120+
119121**`%meld`**: combine changes; if both sides changed the same part of a
120122file, use the version of the file in the merge-base.
121−
123+
122124**`%only-this`**: create a merge commit with exactly the contents of the
123125destination `desk`.
124−
126+
125127**`%only-that`**: create a merge commit with exactly the contents of the
126128source commit.
127−
129+
128130**`%take-this`**: create a merge commit with exactly the contents of the
129131destination `desk` except take any files from the source commit which
130132are not in the destination `desk`.
131−
133+
132134**`%take-that`**: create a merge commit with exactly the contents of the
133135source commit except preserve any files from the destination `desk`
134136which are not in the source commit.
135−
137+
136138**`%meet-this`**: merge as in `%meet`, except if both sides changed the same
137139file, use the version in the destination `desk`.
138−
140+
139141**`%meet-that`**: merge as in `%meet`, except if both sides changed the same
140142file, use the version in the source commit.
141−
143+
142144#### Examples and notes:
143−
145+
144146The most common merge strategy is `%mate`, which is a normal 3-way
145147merge which aborts on conflict.
146−
147−`%take-that` is useful to "force" an OTA. After running `%take-that`,
148+
149+`%take-that` is useful to "force" an OTA. After running `%take-that`,
148150you're guaranteed to have exactly the files in the source commit plus
149151any files you separately added.
150−
151−We speak of merging into a destination *`desk`* from a source *commit*
152+
153+We speak of merging into a destination _`desk`_ from a source _commit_
152154because while you can only merge on top of a `desk`, you can merge from
153−historical commits. For example,
154−```
155−|merge %old our %home, =cas ud+5, =gem %init
155+historical commits. For example,
156+
157+```
158+|merge %old our %base, =cas ud+5, =gem %init
156159```
157−will create a new `desk` called `%old` with the 5th commit in `%home`.
160+
161+will create a new `desk` called `%old` with the 5th commit in `%base`.
158162You can revert the contents of a `desk` to what they were yesterday
159163with
164+
160165```
161−|merge %home our %home, =cas da+(sub now ~d1), =gem %only-that
166+|merge %base our %base, =cas da+(sub now ~d1), =gem %only-that
162167```
163−
168+
164169Note this is a normal `%only-that merge`, which means you're creating a
165−*new* commit with the old *contents*.
166−
170+_new_ commit with the old _contents_.
171+
167172`%meld` is rarely used on its own, however if you specify `%auto` or
168173omit the merge strategy, `%kiln` will run a `%meld` merge into a scratch
169174`desk` and then annotate the conflicts there.
170−
175+
171176If you resolve merge conflicts manually, for example by mounting the
172177`desk`s, copying the files in Unix and then running `|commit`, you
173−should usually run an `%only-this merge`. This will not change the
178+should usually run an `%only-this merge`. This will not change the
174179newly-fixed contents of your `desk`, but it will record that the merge
175180happened so that those conflicts don't reappear in later merges.
176−
181+
177182If you get a `%merge-no-merge-base` error, this means you're trying to
178−merge two `desk`s which have no common ancestors. You need to give
183+merge two `desk`s which have no common ancestors. You need to give
179184them a common ancestor by choosing a merge strategy which doesn't
180185need a merge-base, like `%only-this`, `%only-that`, `%take-this`, or
181186`%take-that`.
182−
187+
183188`%take-this` could be useful to install 3rd party software, but you
184189couldn't get subsequent updates this way, since the files would
185−already exist in the destination `desk`. Something like "take only
190+already exist in the destination `desk`. Something like "take only
186191the files which aren't in my OTA source or any other 3rd party app"
187−would be basically correct. This would require a parameter listing
192+would be basically correct. This would require a parameter listing
188193the `desk`s to not conflict with.
189−
194+
190195`%meet-this` and `%meet-that` imply the existence of `%mate-this` and
191196`%mate-that`, but those don't exist yet.
192197
193198### Autosync
194199
195200Usage:
201+
196202```
197203|sync %target-desk ~source-ship %source-desk
198204```