Google Git
Sign in
chromium / external / gitster / git-htmldocs / 103b5722e7729973bb843e748abe7d4c8f8f9a28 / . / howto / using-merge-subtree.html
blob: 322188a84b8f863df63419695e178dfc1c9af846 [file] [log] [blame]
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]6<meta name="generator" content="AsciiDoc 8.4.5" />
7<title>How to use the subtree merge strategy</title>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]8<style type="text/css">
9/* Debug borders */
10p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11/*
12 border: 1px solid red;
13*/
14}
15
16body {
17 margin: 1em 5% 1em 5%;
18}
19
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]20a {
21 color: blue;
22 text-decoration: underline;
23}
24a:visited {
25 color: fuchsia;
26}
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]27
28em {
29 font-style: italic;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]30 color: navy;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]31}
32
33strong {
34 font-weight: bold;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]35 color: #083194;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]36}
37
38tt {
39 color: navy;
40}
41
42h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
48}
49
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]50h1, h2, h3 {
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]51 border-bottom: 2px solid silver;
52}
53h2 {
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]54 padding-top: 0.5em;
55}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]56h3 {
57 float: left;
58}
59h3 + * {
60 clear: left;
61}
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]62
63div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
66}
67
68hr {
69 border: 1px solid silver;
70}
71
72p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
75}
76
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]77ul, ol, li > p {
78 margin-top: 0;
79}
80
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]81pre {
82 padding: 0;
83 margin: 0;
84}
85
86span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]90 font-size: 1.1em;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]91}
92span#email {
93}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]94span#revnumber, span#revdate, span#revremark {
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]95 font-family: sans-serif;
96}
97
98div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
104}
105div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
108}
109div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
112}
113
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]114div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
117}
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]118div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120div.admonitionblock {
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]121 margin-top: 1.5em;
122 margin-bottom: 1.5em;
123}
124div.admonitionblock {
125 margin-top: 2.5em;
126 margin-bottom: 2.5em;
127}
128
129div.content { /* Block element content. */
130 padding: 0;
131}
132
133/* Block element titles. */
134div.title, caption.title {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]135 color: #527bbd;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]136 font-family: sans-serif;
137 font-weight: bold;
138 text-align: left;
139 margin-top: 1.0em;
140 margin-bottom: 0.5em;
141}
142div.title + * {
143 margin-top: 0;
144}
145
146td div.title:first-child {
147 margin-top: 0.0em;
148}
149div.content div.title:first-child {
150 margin-top: 0.0em;
151}
152div.content + div.title {
153 margin-top: 0.0em;
154}
155
156div.sidebarblock > div.content {
157 background: #ffffee;
158 border: 1px solid silver;
159 padding: 0.5em;
160}
161
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]162div.listingblock > div.content {
163 border: 1px solid silver;
164 background: #f4f4f4;
165 padding: 0.5em;
166}
167
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]168div.quoteblock {
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]169 padding-left: 2.0em;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]170 margin-right: 10%;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]171}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]172div.quoteblock > div.attribution {
173 padding-top: 0.5em;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]174 text-align: right;
175}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]176
177div.verseblock {
178 padding-left: 2.0em;
179 margin-right: 10%;
180}
181div.verseblock > div.content {
182 white-space: pre;
183}
184div.verseblock > div.attribution {
185 padding-top: 0.75em;
186 text-align: left;
187}
188/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]189div.verseblock + div.attribution {
190 text-align: left;
191}
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]192
193div.admonitionblock .icon {
194 vertical-align: top;
195 font-size: 1.1em;
196 font-weight: bold;
197 text-decoration: underline;
198 color: #527bbd;
199 padding-right: 0.5em;
200}
201div.admonitionblock td.content {
202 padding-left: 0.5em;
203 border-left: 2px solid silver;
204}
205
206div.exampleblock > div.content {
207 border-left: 2px solid silver;
208 padding: 0.5em;
209}
210
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]211div.imageblock div.content { padding-left: 0; }
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]212span.image img { border-style: none; }
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]213a.image:visited { color: white; }
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]214
215dl {
216 margin-top: 0.8em;
217 margin-bottom: 0.8em;
218}
219dt {
220 margin-top: 0.5em;
221 margin-bottom: 0;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]222 font-style: normal;
223 color: navy;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]224}
225dd > *:first-child {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]226 margin-top: 0.1em;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]227}
228
229ul, ol {
230 list-style-position: outside;
231}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]232ol.arabic {
233 list-style-type: decimal;
234}
235ol.loweralpha {
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]236 list-style-type: lower-alpha;
237}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]238ol.upperalpha {
239 list-style-type: upper-alpha;
240}
241ol.lowerroman {
242 list-style-type: lower-roman;
243}
244ol.upperroman {
245 list-style-type: upper-roman;
246}
247
248div.compact ul, div.compact ol,
249div.compact p, div.compact p,
250div.compact div, div.compact div {
251 margin-top: 0.1em;
252 margin-bottom: 0.1em;
253}
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]254
255div.tableblock > table {
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]256 border: 3px solid #527bbd;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]257}
258thead {
259 font-family: sans-serif;
260 font-weight: bold;
261}
262tfoot {
263 font-weight: bold;
264}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]265td > div.verse {
266 white-space: pre;
267}
268p.table {
269 margin-top: 0;
270}
271/* Because the table frame attribute is overriden by CSS in most browsers. */
272div.tableblock > table[frame="void"] {
273 border-style: none;
274}
275div.tableblock > table[frame="hsides"] {
276 border-left-style: none;
277 border-right-style: none;
278}
279div.tableblock > table[frame="vsides"] {
280 border-top-style: none;
281 border-bottom-style: none;
282}
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]283
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]284
285div.hdlist {
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]286 margin-top: 0.8em;
287 margin-bottom: 0.8em;
288}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]289div.hdlist tr {
290 padding-bottom: 15px;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]291}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]292dt.hdlist1.strong, td.hdlist1.strong {
293 font-weight: bold;
294}
295td.hdlist1 {
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]296 vertical-align: top;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]297 font-style: normal;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]298 padding-right: 0.8em;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]299 color: navy;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]300}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]301td.hdlist2 {
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]302 vertical-align: top;
303}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]304div.hdlist.compact tr {
305 margin: 0;
306 padding-bottom: 0;
307}
308
309.comment {
310 background: yellow;
311}
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]312
313@media print {
314 div#footer-badges { display: none; }
315}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]316
317div#toctitle {
318 color: #527bbd;
319 font-family: sans-serif;
320 font-size: 1.1em;
321 font-weight: bold;
322 margin-top: 1.0em;
323 margin-bottom: 0.1em;
324}
325
326div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
327 margin-top: 0;
328 margin-bottom: 0;
329}
330div.toclevel2 {
331 margin-left: 2em;
332 font-size: 0.9em;
333}
334div.toclevel3 {
335 margin-left: 4em;
336 font-size: 0.9em;
337}
338div.toclevel4 {
339 margin-left: 6em;
340 font-size: 0.9em;
341}
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]342/* Workarounds for IE6's broken and incomplete CSS2. */
343
344div.sidebar-content {
345 background: #ffffee;
346 border: 1px solid silver;
347 padding: 0.5em;
348}
349div.sidebar-title, div.image-title {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]350 color: #527bbd;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]351 font-family: sans-serif;
352 font-weight: bold;
353 margin-top: 0.0em;
354 margin-bottom: 0.5em;
355}
356
357div.listingblock div.content {
358 border: 1px solid silver;
359 background: #f4f4f4;
360 padding: 0.5em;
361}
362
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]363div.quoteblock-attribution {
364 padding-top: 0.5em;
365 text-align: right;
366}
367
368div.verseblock-content {
369 white-space: pre;
370}
371div.verseblock-attribution {
372 padding-top: 0.75em;
373 text-align: left;
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]374}
375
376div.exampleblock-content {
377 border-left: 2px solid silver;
378 padding-left: 0.5em;
379}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]380
381/* IE6 sets dynamically generated links as visited. */
382div#toc a:visited { color: blue; }
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]383</style>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]384</head>
385<body>
386<div id="header">
387<h1>How to use the subtree merge strategy</h1>
388</div>
389<div id="preamble">
390<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]391<div class="paragraph"><p>There are situations where you want to include contents in your project
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]392from an independently developed project. You can just pull from the
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]393other project as long as there are no conflicting paths.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]394<div class="paragraph"><p>The problematic case is when there are conflicting files. Potential
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]395candidates are Makefiles and other standard filenames. You could merge
396these files but probably you do not want to. A better solution for this
397problem can be to merge the project as its own subdirectory. This is not
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]398supported by the <em>recursive</em> merge strategy, so just pulling won&#8217;t work.</p></div>
399<div class="paragraph"><p>What you want is the <em>subtree</em> merge strategy, which helps you in such a
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]400situation.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]401<div class="paragraph"><p>In this example, let&#8217;s say you have the repository at <tt>/path/to/B</tt> (but
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]402it can be an URL as well, if you want). You want to merge the <em>master</em>
403branch of that repository to the <tt>dir-B</tt> subdirectory in your current
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]404branch.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]405<div class="paragraph"><p>Here is the command sequence you need:</p></div>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]406<div class="listingblock">
407<div class="content">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]408<pre><tt>$ git remote add -f Bproject /path/to/B <b>&lt;1&gt;</b>
409$ git merge -s ours --no-commit Bproject/master <b>&lt;2&gt;</b>
410$ git read-tree --prefix=dir-B/ -u Bproject/master <b>&lt;3&gt;</b>
411$ git commit -m "Merge B project as our subdirectory" <b>&lt;4&gt;</b>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]412
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]413$ git pull -s subtree Bproject master <b>&lt;5&gt;</b></tt></pre>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]414</div></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]415<div class="colist arabic"><ol>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]416<li>
417<p>
418name the other project "Bproject", and fetch.
419</p>
420</li>
421<li>
422<p>
423prepare for the later step to record the result as a merge.
424</p>
425</li>
426<li>
427<p>
428read "master" branch of Bproject to the subdirectory "dir-B".
429</p>
430</li>
431<li>
432<p>
433record the merge result.
434</p>
435</li>
436<li>
437<p>
438maintain the result with subsequent merges using "subtree"
439</p>
440</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]441</ol></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]442<div class="paragraph"><p>The first four commands are used for the initial merge, while the last
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]443one is to merge updates from <em>B project</em>.</p></div>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]444</div>
445</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]446<h2 id="_comparing_em_subtree_em_merge_with_submodules">Comparing <em>subtree</em> merge with submodules</h2>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]447<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]448<div class="ulist"><ul>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]449<li>
450<p>
451The benefit of using subtree merge is that it requires less
452 administrative burden from the users of your repository. It works with
453 older (before Git v1.5.2) clients and you have the code right after
454 clone.
455</p>
456</li>
457<li>
458<p>
459However if you use submodules then you can choose not to transfer the
460 submodule objects. This may be a problem with the subtree merge.
461</p>
462</li>
463<li>
464<p>
465Also, in case you make changes to the other project, it is easier to
466 submit changes if you just use submodules.
467</p>
468</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]469</ul></div>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]470</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]471<h2 id="_additional_tips">Additional tips</h2>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]472<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]473<div class="ulist"><ul>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]474<li>
475<p>
476If you made changes to the other project in your repository, they may
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]477 want to merge from your project. This is possible using subtree&#8201;&#8212;&#8201;it
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]478 can shift up the paths in your tree and then they can merge only the
479 relevant parts of your tree.
480</p>
481</li>
482<li>
483<p>
484Please note that if the other project merges from you, then it will
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]485 connects its history to yours, which can be something they don&#8217;t want
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]486 to.
487</p>
488</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]489</ul></div>
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]490</div>
491<div id="footer">
492<div id="footer-text">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame^]493Last updated 2011-01-31 05:00:33 UTC
Junio C Hamano0e47b232008-01-15 08:31:10[diff] [blame]494</div>
495</div>
496</body>
497</html>