@@ -5,7 +5,6 @@ template = "doc.html"
55aliases = ["/docs/learn/arvo/clay/"]
66+++
77
8−*Current docs on clay are out of date. Until they are updated, this doc remains for historical purposes.*
98
109Our filesystem.
1110
@@ -24,6 +23,127 @@ zuse. Second is the write, query, and subscription logic. Finally, there
2423is the logic for communicating requests to, and receiving requests from,
2524foreign ships.
2625
26+## Merge strategies
27+
28+*This section is up to date as of November 2020*
29+
30+Usage:
31+```
32+|merge %destination-desk ~source-ship %source-desk
33+|merge %destination-desk ~source-ship %source-desk, =gem %strategy
34+|merge %destination-desk ~source-ship %source-desk, =cas ud+5
35+```
36+
37+Clay supports various merge strategies. A "commit" is a snapshot of
38+the files with a list of parents plus a date. Most commits have
39+one parent; a "merge" commit is a commit with two parents. The
40+%home desk starts with an initial commit with no parents; commits
41+with several parents ("octopus merges") are possible but we don't
42+generate them right now.
43+
44+Unless otherwise specified, all of the following create a new commit
45+with the source and destination commits as parents.
46+
47+Several strategies need a "merge-base". They find it by identifying
48+the most recent common ancestor of the two desks. If none, fail
49+with `%merge-no-merge-base`; if there are two or more, pick one.
50+
51+`%init`: the only way to create a desk. Not a true merge, since it
52+simply assigns the source commit to the destination.
53+
54+`%fine`: if source or destination are in the ancestry of each other,
55+use the newer one; else abort. If the destination is ahead of the
56+source, succeed but do nothing. If the source is ahead of the
57+destination, assign the next revision number to the source commit.
58+Some call this "fast-forward".
59+
60+`%meet`: combine changes, failing if both sides changed the same file.
61+Specifically, take diff(merge-base,source) and
62+diff(merge-base,destination) and combine them as long as those diffs
63+touch different files.
64+
65+`%mate`: combine changes, failing if both sides changed the same part
66+of a file. Identical to `%meet`, except that some marks, like `%hoon`,
67+allow intelligent merge of changes to different parts of a file.
68+
69+`%meld`: combine changes; if both sides changed the same part of a
70+file, use the version of the file in the merge-base.
71+
72+`%only-this`: create a merge commit with exactly the contents of the
73+destination desk.
74+
75+`%only-that`: create a merge commit with exactly the contents of the
76+source commit.
77+
78+`%take-this`: create a merge commit with exactly the contents of the
79+destination desk except take any files from the source commit which
80+are not in the destination desk.
81+
82+`%take-that`: create a merge commit with exactly the contents of the
83+source commit except preserve any files from the destination desk
84+which are not in the source commit.
85+
86+`%meet-this`: merge as in `%meet`, except if both sides changed the same
87+file, use the version in the destination desk.
88+
89+`%meet-that`: merge as in `%meet`, except if both sides changed the same
90+file, use the version in the source commit.
91+
92+### Examples and notes:
93+
94+The most common merge strategy is %mate, which is a normal 3-way
95+merge which aborts on conflict.
96+
97+`%take-that` is useful to "force" an OTA. After running `%take-that`,
98+you're guaranteed to have exactly the files in the source commit plus
99+any files you separately added.
100+
101+We speak of merging into a destination *desk* from a source *commit*
102+because while you can only merge on top of a desk, you can merge from
103+historical commits. For example,
104+```
105+|merge %old our %home, =cas ud+5, =gem %init
106+```
107+will create a new desk called `%old` with the 5th commit in `%home`.
108+You can revert the contents of a desk to what they were yesterday
109+with
110+```
111+|merge %home our %home, =cas da+(sub now ~d1), =gem %only-that
112+```
113+
114+Note this is a normal `%only-that merge`, which means you're creating a
115+*new* commit with the old *contents*.
116+
117+`%meld` is rarely used on its own, however if you specify `%auto` or
118+omit the merge strategy, `%kiln` will run a `%meld` merge into a scratch
119+desk and then annotate the conflicts there.
120+
121+If you resolve merge conflicts manually, for example by mounting the
122+desks, copying the files in Unix and then running `|commit`, you
123+should usually run an `%only-this merge`. This will not change the
124+newly-fixed contents of your desk, but it will record that the merge
125+happened so that those conflicts don't reappear in later merges.
126+
127+If you get a `%merge-no-merge-base` error, this means you're trying to
128+merge two desks which have no common ancestors. You need to give
129+them a common ancestor by choosing a merge strategy which doesn't
130+need a merge-base, like `%only-this`, `%only-that`, `%take-this`, or
131+`%take-that`.
132+
133+`%take-this` could be useful to install 3rd party software, but you
134+couldn't get subsequent updates this way, since the files would
135+already exist in the destination desk. Something like "take only
136+the files which aren't in my OTA source or any other 3rd party app"
137+would be basically correct. This would require a parameter listing
138+the desks to not conflict with.
139+
140+`%meet-this` and `%meet-that` imply the existence of `%mate-this` and
141+`%mate-that`, but those don't exist yet.
142+
143+
144+*The remainder of this document is out of date as of November 2020, but certain parts are still
145+accurate. Please independently confirm information here before acting on it.*
146+
27147## Architecture
28148
29149Clay is the primary filesystem for the arvo operating system,