Re: [PATCH] Add [HOWTO] using merge subtree.

Miklos Vajna [off-list ref] 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: [ref]
+
+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'".