@@ -0,0 +1,150 @@
7+Here we'll look at merging desks programmatically.
9+A `%merg` tagged `task:clay` will merge the specified source desk into the target local desk. It looks like:
12+$: %merg :: merge desks
14+ her=@p dem=desk cas=case :: source
19+The `germ` specifies the merge strategy and looks like:
22++$ germ :: merge style
24+ %fine :: fast forward
25+ %meet :: orthogonal files
26+ %mate :: orthogonal changes
28+ %only-this :: ours with parents
29+ %only-that :: hers with parents
30+ %take-this :: ours unless absent
31+ %take-that :: hers unless absent
32+ %meet-this :: ours if conflict
33+ %meet-that :: hers if conflict
37+You can refer to the [Strategies](@/docs/arvo/clay/using.md#strategies) section of the [Using Clay](@/docs/arvo/clay/using.md) document for details of each `germ`.
39+If you're merging into a new desk you must use `%init`, all other strategies will fail. If the desk already exists, you cannot use `%init`. Otherwise, you're free to use whichever you'd like.
41+Clay will respond to the request with a `%mere` tagged `gift:clay` which looks like:
44+[%mere p=(each (set path) (pair term tang))] :: merge result
47+If the merge succeeded, `p` will look like `[%mere p=[%.y p={}]]` where `p.p` is the set of files which had a merge conflict. For example, `[%mere p=[%.y p={/foo/txt}]]` means there was a conflict with `/foo/txt`. An empty set means there were no conflicts.
49+If the merge failed, `p` will have a head of `%.n` and then a `[term tang]` where the `term` is an error message and the `tang` contains additional details, for example:
55+ p=[p=%mate-conflict q=~[[%rose p=[p="/" q="/" r=""] q=~[[%leaf p="foo"] [%leaf p="txt"]]]]]
62+Here's a thread that sends the given `task:clay` to clay and prints the `gift:clay` response:
69+=, strand=strand:spider
74+=/ uarg !< (unit task:clay) arg
76+ (strand-fail:strand %no-arg ~)
78+=/ =card:agent:gall [%pass /foo %arvo %c task]
79+;< ~ bind:m (send-raw-card:strandio card)
83+Save it to `ted/send-task.hoon` and `|commit %home`.
85+First, let's try creating a new desk:
88+> -send-task-take-gift [%merg %foo our %home da+now %init]
92+Now if we scry for our desks we'll see `%foo` is there:
95+> .^((set desk) %cd /===)
99+Next, we'll create a merge conflict and try a couple of things. Mount `%foo` with `|mount /=foo=`, then add a `foo.txt` to both desks but with different text in each and `|commit` them.
101+Now we'll try merging `%home` into `%foo` with a `%mate` strategy:
104+> -send-task-take-gift [%merg %foo our %home da+now %mate]
112+ q=~[[%rose p=[p="/" q="/" r=""] q=[i=[%leaf p="foo"] t=[i=[%leaf p="txt"] t=~]]]]
120+As you can see, the merge has failed. Let's try again with a `%meld` strategy:
123+> -send-task-take-gift [%merg %foo our %home da+now %meld]
124+[/foo [%clay [%mere p=[%.y p={/foo/txt}]]]]
127+Now the merge has succeeded and the `%mere` notes the file with a merge conflict. If we try with a `%only-that` strategy:
130+> -send-task-take-gift [%merg %foo our %home da+now %only-that]
131+[/foo [%clay [%mere p=[%.y p={}]]]]
132+: /~zod/foo/6/foo/txt
135+...you can see it's overwritten the `foo/txt` in the `%foo` desk and the `%mere` now has an empty set, indicating no merge conflicts.
137+Next, let's look at subscribing for future changes. Since the `case` is specified explicitly in the `%merge` task, we can set in in the future:
140+> -send-task-take-gift [%merg %foo our %home da+(add ~m2 now) %only-that]
143+Now change the text in the `foo.txt` in the `%home` desk, hit backspace to detach the thread and `|commit %home`. After the two minutes pass you should see:
146+[/foo [%clay [%mere p=[%.y p={}]]]]
147+: /~zod/foo/7/foo/txt
150+You can also specify it by revision number or label.