@@ -5,7 +5,6 @@ template = "doc.html"
5aliases = ["/docs/learn/arvo/clay/"]
5aliases = ["/docs/learn/arvo/clay/"]
8−*Current docs on clay are out of date. Until they are updated, this doc remains for historical purposes.*
10Our filesystem.
9Our filesystem.
@@ -24,6 +23,127 @@ zuse. Second is the write, query, and subscription logic. Finally, there
24is the logic for communicating requests to, and receiving requests from,
23is the logic for communicating requests to, and receiving requests from,
25foreign ships.
24foreign ships.
28+*This section is up to date as of November 2020*
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
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.
44+Unless otherwise specified, all of the following create a new commit
45+with the source and destination commits as parents.
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.
51+`%init`: the only way to create a desk. Not a true merge, since it
52+simply assigns the source commit to the destination.
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".
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.
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.
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.
72+`%only-this`: create a merge commit with exactly the contents of the
75+`%only-that`: create a merge commit with exactly the contents of the
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.
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.
86+`%meet-this`: merge as in `%meet`, except if both sides changed the same
87+file, use the version in the destination desk.
89+`%meet-that`: merge as in `%meet`, except if both sides changed the same
90+file, use the version in the source commit.
92+### Examples and notes:
94+The most common merge strategy is %mate, which is a normal 3-way
95+merge which aborts on conflict.
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.
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,
105+|merge %old our %home, =cas ud+5, =gem %init
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
111+|merge %home our %home, =cas da+(sub now ~d1), =gem %only-that
114+Note this is a normal `%only-that merge`, which means you're creating a
115+*new* commit with the old *contents*.
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.
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.
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
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.
140+`%meet-this` and `%meet-that` imply the existence of `%mate-this` and
141+`%mate-that`, but those don't exist yet.
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.*
27## Architecture
147## Architecture
29Clay is the primary filesystem for the arvo operating system,
149Clay is the primary filesystem for the arvo operating system,