@@ -0,0 +1,150 @@
1++++
2+title = "Merge Desks"
3+weight = 9
4+template = "doc.html"
5++++
6+
7+Here we'll look at merging desks programmatically.
8+
9+A `%merg` tagged `task:clay` will merge the specified source desk into the target local desk. It looks like:
10+
11+```hoon
12+$: %merg :: merge desks
13+ des=desk :: target
14+ her=@p dem=desk cas=case :: source
15+ how=germ :: method
16+== ::
17+```
18+
19+The `germ` specifies the merge strategy and looks like:
20+
21+```hoon
22++$ germ :: merge style
23+ $? %init :: new desk
24+ %fine :: fast forward
25+ %meet :: orthogonal files
26+ %mate :: orthogonal changes
27+ %meld :: force merge
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
34+ == ::
35+```
36+
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`.
38+
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.
40+
41+Clay will respond to the request with a `%mere` tagged `gift:clay` which looks like:
42+
43+```hoon
44+[%mere p=(each (set path) (pair term tang))] :: merge result
45+```
46+
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.
48+
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:
50+
51+```hoon
52+[ %mere
53+ p
54+ [ %.n
55+ p=[p=%mate-conflict q=~[[%rose p=[p="/" q="/" r=""] q=~[[%leaf p="foo"] [%leaf p="txt"]]]]]
56+ ]
57+]
58+```
59+
60+Example:
61+
62+Here's a thread that sends the given `task:clay` to clay and prints the `gift:clay` response:
63+
64+**`send-task.hoon`**
65+
66+```hoon
67+/- spider
68+/+ strandio
69+=, strand=strand:spider
70+^- thread:spider
71+|= arg=vase
72+=/ m (strand ,vase)
73+^- form:m
74+=/ uarg !< (unit task:clay) arg
75+?~ uarg
76+ (strand-fail:strand %no-arg ~)
77+=/ =task:clay u.uarg
78+=/ =card:agent:gall [%pass /foo %arvo %c task]
79+;< ~ bind:m (send-raw-card:strandio card)
80+(pure:m !>(~))
81+```
82+
83+Save it to `ted/send-task.hoon` and `|commit %home`.
84+
85+First, let's try creating a new desk:
86+
87+```hoon
88+> -send-task-take-gift [%merg %foo our %home da+now %init]
89+[%mere p=[%.y p={}]]
90+```
91+
92+Now if we scry for our desks we'll see `%foo` is there:
93+
94+```hoon
95+> .^((set desk) %cd /===)
96+{%home %foo %kids}
97+```
98+
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.
100+
101+Now we'll try merging `%home` into `%foo` with a `%mate` strategy:
102+
103+```hoon
104+> -send-task-take-gift [%merg %foo our %home da+now %mate]
105+[ /foo
106+ [ %clay
107+ [ %mere
108+ p
109+ [ %.n
110+ p
111+ [ p=%mate-conflict
112+ q=~[[%rose p=[p="/" q="/" r=""] q=[i=[%leaf p="foo"] t=[i=[%leaf p="txt"] t=~]]]]
113+ ]
114+ ]
115+ ]
116+ ]
117+]
118+```
119+
120+As you can see, the merge has failed. Let's try again with a `%meld` strategy:
121+
122+```hoon
123+> -send-task-take-gift [%merg %foo our %home da+now %meld]
124+[/foo [%clay [%mere p=[%.y p={/foo/txt}]]]]
125+```
126+
127+Now the merge has succeeded and the `%mere` notes the file with a merge conflict. If we try with a `%only-that` strategy:
128+
129+```hoon
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
133+```
134+
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.
136+
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:
138+
139+```hoon
140+> -send-task-take-gift [%merg %foo our %home da+(add ~m2 now) %only-that]
141+```
142+
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:
144+
145+```hoon
146+[/foo [%clay [%mere p=[%.y p={}]]]]
147+: /~zod/foo/7/foo/txt
148+```
149+
150+You can also specify it by revision number or label.