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">
5 <meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" />
6 <meta name=
"generator" content=
"AsciiDoc 8.5.2" />
7 <title>How to use the subtree merge strategy
</title>
8 <style type=
"text/css">
10 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
12 border: 1px solid red;
17 margin: 1em 5% 1em 5%;
22 text-decoration: underline
;
42 h1
, h2
, h3
, h4
, h5
, h6
{
44 font-family: sans-serif
;
51 border-bottom: 2px solid silver
;
69 border: 1px solid silver
;
88 font-family: sans-serif
;
94 span#revnumber
, span#revdate
, span#revremark
{
95 font-family: sans-serif
;
99 font-family: sans-serif
;
101 border-top: 2px solid silver
;
107 padding-bottom: 0.5em;
111 padding-bottom: 0.5em;
116 margin-bottom: 1.5em;
118 div
.tableblock
, div
.imageblock
, div
.exampleblock
, div
.verseblock
,
119 div
.quoteblock
, div
.literalblock
, div
.listingblock
, div
.sidebarblock
,
120 div
.admonitionblock
{
122 margin-bottom: 1.5em;
124 div
.admonitionblock
{
126 margin-bottom: 2.0em;
131 div
.content
{ /* Block element content. */
135 /* Block element titles. */
136 div
.title
, caption
.title
{
138 font-family: sans-serif
;
142 margin-bottom: 0.5em;
148 td div
.title:first-child
{
151 div
.content div
.title:first-child
{
154 div
.content
+ div
.title
{
158 div
.sidebarblock
> div
.content
{
160 border: 1px solid silver
;
164 div
.listingblock
> div
.content
{
165 border: 1px solid silver
;
170 div
.quoteblock
, div
.verseblock
{
174 border-left: 5px solid
#dddddd;
178 div
.quoteblock
> div
.attribution
{
183 div
.verseblock
> div
.content
{
186 div
.verseblock
> div
.attribution
{
190 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191 div
.verseblock
+ div
.attribution
{
195 div
.admonitionblock
.icon
{
199 text-decoration: underline
;
201 padding-right: 0.5em;
203 div
.admonitionblock td
.content
{
205 border-left: 3px solid
#dddddd;
208 div
.exampleblock
> div
.content
{
209 border-left: 3px solid
#dddddd;
213 div
.imageblock div
.content
{ padding-left: 0; }
214 span
.image img
{ border-style: none
; }
215 a
.image:visited
{ color: white
; }
219 margin-bottom: 0.8em;
232 list-style-position: outside
;
235 list-style-type: decimal
;
238 list-style-type: lower-alpha
;
241 list-style-type: upper-alpha
;
244 list-style-type: lower-roman
;
247 list-style-type: upper-roman
;
250 div
.compact ul
, div
.compact ol
,
251 div
.compact p
, div
.compact p
,
252 div
.compact div
, div
.compact div
{
254 margin-bottom: 0.1em;
257 div
.tableblock
> table
{
258 border: 3px solid
#527bbd;
260 thead
, p
.table
.header
{
261 font-family: sans-serif
;
273 /* Because the table frame attribute is overriden by CSS in most browsers. */
274 div
.tableblock
> table
[frame
="void"] {
277 div
.tableblock
> table
[frame
="hsides"] {
278 border-left-style: none
;
279 border-right-style: none
;
281 div
.tableblock
> table
[frame
="vsides"] {
282 border-top-style: none
;
283 border-bottom-style: none
;
289 margin-bottom: 0.8em;
292 padding-bottom: 15px;
294 dt
.hdlist1
.strong
, td
.hdlist1
.strong
{
300 padding-right: 0.8em;
306 div
.hdlist
.compact tr
{
315 .footnote, .footnoteref {
319 span
.footnote
, span
.footnoteref
{
320 vertical-align: super
;
324 margin: 20px 0 20px 0;
328 #footnotes div
.footnote
{
334 border-top: 1px solid silver
;
344 div#footer-badges
{ display: none
; }
348 margin-bottom: 2.5em;
353 font-family: sans-serif
;
357 margin-bottom: 0.1em;
360 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
376 /* Workarounds for IE6's broken and incomplete CSS2. */
378 div
.sidebar-content
{
380 border: 1px solid silver
;
383 div
.sidebar-title
, div
.image-title
{
385 font-family: sans-serif
;
388 margin-bottom: 0.5em;
391 div
.listingblock div
.content
{
392 border: 1px solid silver
;
397 div
.quoteblock-attribution
{
402 div
.verseblock-content
{
405 div
.verseblock-attribution
{
410 div
.exampleblock-content
{
411 border-left: 3px solid
#dddddd;
415 /* IE6 sets dynamically generated links as visited. */
416 div#toc
a:visited
{ color: blue
; }
418 <script type=
"text/javascript">
420 window
.onload = function(){asciidoc
.footnotes();}
421 var asciidoc
= { // Namespace.
423 /////////////////////////////////////////////////////////////////////
424 // Table Of Contents generator
425 /////////////////////////////////////////////////////////////////////
427 /* Author: Mihai Bazon, September 2002
428 * http://students.infoiasi.ro/~mishoo
430 * Table Of Content generator
433 * Feel free to use this script under the terms of the GNU General Public
434 * License, as long as you do not remove or alter this notice.
437 /* modified by Troy D. Hanson, September 2006. License: GPL */
438 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
441 toc: function (toclevels
) {
443 function getText(el
) {
445 for (var i
= el
.firstChild
; i
!= null; i
= i
.nextSibling
) {
446 if (i
.nodeType
== 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
448 else if (i
.firstChild
!= null)
454 function TocEntry(el
, text
, toclevel
) {
457 this.toclevel
= toclevel
;
460 function tocEntries(el
, toclevels
) {
461 var result
= new Array
;
462 var re
= new RegExp('[hH]([2-'+(toclevels
+1)+'])');
463 // Function that scans the DOM tree for header elements (the DOM2
464 // nodeIterator API would be a better technique but not supported by all
466 var iterate = function (el
) {
467 for (var i
= el
.firstChild
; i
!= null; i
= i
.nextSibling
) {
468 if (i
.nodeType
== 1 /* Node.ELEMENT_NODE */) {
469 var mo
= re
.exec(i
.tagName
);
470 if (mo
&& (i
.getAttribute("class") || i
.getAttribute("className")) != "float") {
471 result
[result
.length
] = new TocEntry(i
, getText(i
), mo
[1]-1);
481 var toc
= document
.getElementById("toc");
482 var entries
= tocEntries(document
.getElementById("content"), toclevels
);
483 for (var i
= 0; i
< entries
.length
; ++i
) {
484 var entry
= entries
[i
];
485 if (entry
.element
.id
== "")
486 entry
.element
.id
= "_toc_" + i
;
487 var a
= document
.createElement("a");
488 a
.href
= "#" + entry
.element
.id
;
489 a
.appendChild(document
.createTextNode(entry
.text
));
490 var div
= document
.createElement("div");
492 div
.className
= "toclevel" + entry
.toclevel
;
493 toc
.appendChild(div
);
495 if (entries
.length
== 0)
496 toc
.parentNode
.removeChild(toc
);
500 /////////////////////////////////////////////////////////////////////
501 // Footnotes generator
502 /////////////////////////////////////////////////////////////////////
504 /* Based on footnote generation code from:
505 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
508 footnotes: function () {
509 var cont
= document
.getElementById("content");
510 var noteholder
= document
.getElementById("footnotes");
511 var spans
= cont
.getElementsByTagName("span");
514 for (i
=0; i
<spans
.length
; i
++) {
515 if (spans
[i
].className
== "footnote") {
517 // Use [\s\S] in place of . so multi-line matches work.
518 // Because JavaScript has no s (dotall) regex flag.
519 note
= spans
[i
].innerHTML
.match(/\s*\[([\s\S]*)]\s*/)[1];
520 noteholder
.innerHTML
+=
521 "<div class='footnote' id='_footnote_" + n
+ "'>" +
522 "<a href='#_footnoteref_" + n
+ "' title='Return to text'>" +
523 n
+ "</a>. " + note
+ "</div>";
525 "[<a id='_footnoteref_" + n
+ "' href='#_footnote_" + n
+
526 "' title='View footnote' class='footnote'>" + n
+ "</a>]";
527 var id
=spans
[i
].getAttribute("id");
528 if (id
!= null) refs
["#"+id
] = n
;
532 noteholder
.parentNode
.removeChild(noteholder
);
534 // Process footnoterefs.
535 for (i
=0; i
<spans
.length
; i
++) {
536 if (spans
[i
].className
== "footnoteref") {
537 var href
= spans
[i
].getElementsByTagName("a")[0].getAttribute("href");
538 href
= href
.match(/#.*/)[0]; // Because IE return full URL.
541 "[<a href='#_footnote_" + n
+
542 "' title='View footnote' class='footnote'>" + n
+ "</a>]";
554 <h1>How to use the subtree merge strategy
</h1>
558 <div class=
"sectionbody">
559 <div class=
"paragraph"><p>There are situations where you want to include contents in your project
560 from an independently developed project. You can just pull from the
561 other project as long as there are no conflicting paths.
</p></div>
562 <div class=
"paragraph"><p>The problematic case is when there are conflicting files. Potential
563 candidates are Makefiles and other standard filenames. You could merge
564 these files but probably you do not want to. A better solution for this
565 problem can be to merge the project as its own subdirectory. This is not
566 supported by the
<em>recursive
</em> merge strategy, so just pulling won
’t work.
</p></div>
567 <div class=
"paragraph"><p>What you want is the
<em>subtree
</em> merge strategy, which helps you in such a
569 <div class=
"paragraph"><p>In this example, let
’s say you have the repository at
<tt>/path/to/B
</tt> (but
570 it can be an URL as well, if you want). You want to merge the
<em>master
</em>
571 branch of that repository to the
<tt>dir-B
</tt> subdirectory in your current
573 <div class=
"paragraph"><p>Here is the command sequence you need:
</p></div>
574 <div class=
"listingblock">
575 <div class=
"content">
576 <pre><tt>$ git remote add -f Bproject /path/to/B
<b><1></b>
577 $ git merge -s ours --no-commit Bproject/master
<b><2></b>
578 $ git read-tree --prefix=dir-B/ -u Bproject/master
<b><3></b>
579 $ git commit -m
"Merge B project as our subdirectory" <b><4></b>
581 $ git pull -s subtree Bproject master
<b><5></b></tt></pre>
583 <div class=
"colist arabic"><ol>
586 name the other project
"Bproject", and fetch.
591 prepare for the later step to record the result as a merge.
596 read
"master" branch of Bproject to the subdirectory
"dir-B".
601 record the merge result.
606 maintain the result with subsequent merges using
"subtree"
610 <div class=
"paragraph"><p>The first four commands are used for the initial merge, while the last
611 one is to merge updates from
<em>B project
</em>.
</p></div>
614 <h2 id=
"_comparing_em_subtree_em_merge_with_submodules">Comparing
<em>subtree
</em> merge with submodules
</h2>
615 <div class=
"sectionbody">
616 <div class=
"ulist"><ul>
619 The benefit of using subtree merge is that it requires less
620 administrative burden from the users of your repository. It works with
621 older (before Git v1.5
.2) clients and you have the code right after
627 However if you use submodules then you can choose not to transfer the
628 submodule objects. This may be a problem with the subtree merge.
633 Also, in case you make changes to the other project, it is easier to
634 submit changes if you just use submodules.
639 <h2 id=
"_additional_tips">Additional tips
</h2>
640 <div class=
"sectionbody">
641 <div class=
"ulist"><ul>
644 If you made changes to the other project in your repository, they may
645 want to merge from your project. This is possible using subtree
 — it
646 can shift up the paths in your tree and then they can merge only the
647 relevant parts of your tree.
652 Please note that if the other project merges from you, then it will
653 connect its history to yours, which can be something they don
’t want
660 <div id=
"footnotes"><hr /></div>
662 <div id=
"footer-text">
663 Last updated
2011-
09-
21 23:
17:
57 PDT