# Re: [PATCH] Add [HOWTO] using merge subtree. 3 messages from 2008-01-09 to 2008-01-09. Participants: Junio C Hamano. Thread: https://gitlist.dev/t/11544 ## Junio C Hamano, 2008-01-09 01:35 Subject: Re: [PATCH] Add [HOWTO] using merge subtree. Message-ID: <7vwsqjpyqi.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vwsqjpyqi.fsf%40gitster.siamese.dyndns.org In-Reply-To: <1199838182-15178-1-git-send-email-vmiklos@frugalware.org> ``` Miklos Vajna writes: NAK. It may be well intentioned, but it lacks too much context to be usable as a generic teaching material. > +Abstract: In this article, Sean demonstrates how one can use the subtree merge > + strategy. > +Message-ID: > + > +How to use the subtree merge strategy > +===================================== Here, before diving to the actual command sequence, you need to tell the reader what the objective of the whole exercise is. What's /path/to/B and how its contents relate to the contents of the current repository? How was that other repository prepared? What's the ultimate goal, IOW, what overlayed tree layout are you trying to create? Why do you want to have that overlayed layout? When you heard it on the mailing list you may have had enough background material from the discussion thread. Your readers won't have that. > +---- > +$ git remote add -f B /path/to/B <1> > +$ git merge -s ours --no-commit B/master <2> > +$ git read-tree --prefix=B/ -u B/master <3> > +$ git commit -m "Merge commit 'B/master'" <4> > +---- > +<1> creates and fetches the remote. > +<2> initiates a merge, but stops before committing it. > +<3> reads B/master into the subdirectory "sub". > +<4> all that remains is committing the completed merge. > + > +You only need this procedure for the first commit, after which `git merge -s > +subtree B/master` is all you need. Complaints for an overly long line aside, after that description, having another code example block to illustrate the exact command line would be more consistent with the above display. Alternatively, make it <5> and annotate that entry with "You only need the above four steps once, after that you can keep doing 'git pull -s subtree B master'". ``` ## Junio C Hamano, 2008-01-09 03:46 Subject: Re: [PATCH] Add [HOWTO] using merge subtree. Message-ID: <7vfxx7psoq.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vfxx7psoq.fsf%40gitster.siamese.dyndns.org In-Reply-To: <7vwsqjpyqi.fsf@gitster.siamese.dyndns.org> ``` Junio C Hamano writes: > Miklos Vajna writes: > > NAK. It may be well intentioned, but it lacks too much context > to be usable as a generic teaching material. > >> +Abstract: In this article, Sean demonstrates how one can use the subtree merge >> + strategy. >> +Message-ID: >> + >> +How to use the subtree merge strategy >> +===================================== > > Here, before diving to the actual command sequence, you need to > tell the reader what the objective of the whole exercise is. Just to avoid discouraging contributors too much, here are pointers to some other materials in the mailing list archive that may serve as the basis for the "discussion" section of this HOWTO. Side note. I think an ideal HOWTO should - describe the objective briefly so that the reader can tell if that is relevant to the task at hand; - describe the procedure; - mention other possible avenues and discuss pros and cons, so that the reader can make an informed decision to employ or not to employ the solution. My complaints were that the original had only the second part. And this message is to give pointers to possible material for the third part. * http://thread.gmane.org/gmane.comp.version-control.git/39443 This was the explanation on the way how the initial git-gui subtree merge was created. * http://thread.gmane.org/gmane.comp.version-control.git/39963 The introduction of subtree strategy. The original cover letter and the following discussion is rich with discussions on merge philosophy and pros and cons. Back then "submodule" was not available, and we would still avoid it today in git.git, because use of submodule in a repository would make the repository non-interoperable with any clients older than 1.5.2 series (that's one pros-and-cons item). Somewhere in the thread it was also suggested "am -pN" may be necessary. * http://thread.gmane.org/gmane.comp.version-control.git/46569/focus=46609 This is a side note -- it turns out that "am -pN" used on the context of subtree merge is often not necessary, as --3way is a magic. ``` ## Junio C Hamano, 2008-01-09 06:28 Subject: Re: [PATCH] Add [HOWTO] using merge subtree. Message-ID: <7v8x2zpl6n.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7v8x2zpl6n.fsf%40gitster.siamese.dyndns.org In-Reply-To: <7vfxx7psoq.fsf@gitster.siamese.dyndns.org> ``` Junio C Hamano writes: > * http://thread.gmane.org/gmane.comp.version-control.git/39443 > > This was the explanation on the way how the initial git-gui > subtree merge was created. For the record, the very first cross-project merge is: http://thread.gmane.org/gmane.comp.version-control.git/5126 The procedure to maintain the resulting re-merge of two histories do not involve subtree merge because "The coolest merge ever" merges non-overlapping two trees at the same level, but the principle used to bootstrap the process is the same. You prepare a tree that is a overlay of the tips of your two projects, and record that tree in a commit that is a merge between two parents. ```