{"thread":{"id":"11544","subject":"Re: [PATCH] Add [HOWTO] using merge subtree.","startedAt":"2008-01-09T01:35:33Z","lastAt":"2008-01-09T06:28:16Z","messageCount":3,"participants":["Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"64802","messageId":"7vwsqjpyqi.fsf@gitster.siamese.dyndns.org","threadId":"11544","inReplyTo":"1199838182-15178-1-git-send-email-vmiklos@frugalware.org","subject":"Re: [PATCH] Add [HOWTO] using merge subtree.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-01-09T01:35:33Z","receivedAt":"2008-01-09T01:35:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Miklos Vajna writes:\n\nNAK. It may be well intentioned, but it lacks too much context\nto be usable as a generic teaching material.\n\n> +Abstract: In this article, Sean demonstrates how one can use the subtree merge\n> + strategy.\n> +Message-ID: \n> +\n> +How to use the subtree merge strategy\n> +=====================================\n\nHere, before diving to the actual command sequence, you need to\ntell the reader what the objective of the whole exercise is.\n\nWhat's /path/to/B and how its contents relate to the contents of\nthe current repository? How was that other repository prepared?\nWhat's the ultimate goal, IOW, what overlayed tree layout are\nyou trying to create? Why do you want to have that overlayed\nlayout?\n\nWhen you heard it on the mailing list you may have had enough\nbackground material from the discussion thread. Your readers\nwon't have that.\n\n> +----\n> +$ git remote add -f B /path/to/B <1>\n> +$ git merge -s ours --no-commit B/master <2>\n> +$ git read-tree --prefix=B/ -u B/master <3>\n> +$ git commit -m \"Merge commit 'B/master'\" <4>\n> +----\n> +<1> creates and fetches the remote.\n> +<2> initiates a merge, but stops before committing it.\n> +<3> reads B/master into the subdirectory \"sub\".\n> +<4> all that remains is committing the completed merge.\n> +\n> +You only need this procedure for the first commit, after which `git merge -s\n> +subtree B/master` is all you need.\n\nComplaints for an overly long line aside, after that\ndescription, having another code example block to illustrate the\nexact command line would be more consistent with the above\ndisplay. Alternatively, make it <5> and annotate that entry\nwith \"You only need the above four steps once, after that you\ncan keep doing 'git pull -s subtree B master'\".\n"},{"id":"64811","messageId":"7vfxx7psoq.fsf@gitster.siamese.dyndns.org","threadId":"11544","inReplyTo":"7vwsqjpyqi.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Add [HOWTO] using merge subtree.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-01-09T03:46:13Z","receivedAt":"2008-01-09T03:46:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Miklos Vajna writes:\n>\n> NAK. It may be well intentioned, but it lacks too much context\n> to be usable as a generic teaching material.\n>\n>> +Abstract: In this article, Sean demonstrates how one can use the subtree merge\n>> + strategy.\n>> +Message-ID: \n>> +\n>> +How to use the subtree merge strategy\n>> +=====================================\n> \n> Here, before diving to the actual command sequence, you need to\n> tell the reader what the objective of the whole exercise is.\n\nJust to avoid discouraging contributors too much, here are\npointers to some other materials in the mailing list archive\nthat may serve as the basis for the \"discussion\" section of this\nHOWTO.\n\nSide note. I think an ideal HOWTO should\n\n- describe the objective briefly so that the reader can tell if\n that is relevant to the task at hand;\n\n- describe the procedure;\n\n- mention other possible avenues and discuss pros and cons, so\n that the reader can make an informed decision to employ or not\n to employ the solution.\n\nMy complaints were that the original had only the second part.\nAnd this message is to give pointers to possible material for\nthe third part.\n\n\n* http://thread.gmane.org/gmane.comp.version-control.git/39443\n\nThis was the explanation on the way how the initial git-gui\nsubtree merge was created.\n\n* http://thread.gmane.org/gmane.comp.version-control.git/39963\n\nThe introduction of subtree strategy. The original cover letter\nand the following discussion is rich with discussions on merge\nphilosophy and pros and cons.\n\nBack then \"submodule\" was not available, and we would still\navoid it today in git.git, because use of submodule in a\nrepository would make the repository non-interoperable with any\nclients older than 1.5.2 series (that's one pros-and-cons item).\n\nSomewhere in the thread it was also suggested \"am -pN\" may be\nnecessary.\n\n* http://thread.gmane.org/gmane.comp.version-control.git/46569/focus=46609\n\nThis is a side note -- it turns out that \"am -pN\" used on the\ncontext of subtree merge is often not necessary, as --3way is a\nmagic.\n"},{"id":"64816","messageId":"7v8x2zpl6n.fsf@gitster.siamese.dyndns.org","threadId":"11544","inReplyTo":"7vfxx7psoq.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Add [HOWTO] using merge subtree.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-01-09T06:28:16Z","receivedAt":"2008-01-09T06:28:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> * http://thread.gmane.org/gmane.comp.version-control.git/39443\n>\n> This was the explanation on the way how the initial git-gui\n> subtree merge was created.\n\nFor the record, the very first cross-project merge is:\n\n http://thread.gmane.org/gmane.comp.version-control.git/5126\n\nThe procedure to maintain the resulting re-merge of two\nhistories do not involve subtree merge because \"The coolest\nmerge ever\" merges non-overlapping two trees at the same level,\nbut the principle used to bootstrap the process is the same.\nYou prepare a tree that is a overlay of the tips of your two\nprojects, and record that tree in a commit that is a merge\nbetween two parents.\n"}]}