I think the presentation order is still screwy.  Before saying

what it does, let's state why the reader might want to use what

we are going to describe, so that the reader can say "I am not

in that situation, I do not have to read the rest" and skip the

document quickly.
    When you want to include contents in your project from

    another project that has started its life independently, you

    can do so by merging the other project into your project.

    If there is no (and more importantly if there will never be

    any) overlap in paths the two project have, you can merge

    them without any tricks.
    However, if there are overlapping paths (e.g. you have

    Makefile, they have Makefile but as separate projects, these

    two Makefiles do not have anything to do with each other),

    you have a problem.  You do not necessarily have the option

    to merge these Makefiles together.  Instead, you may want to

    merge the other project as a subdirectory in your project.
    The 'subtree' merge strategy is designed to help you in such

    a situation.
Then give the birds-eye-view of the names you use in the example

description, so that the readers can substitute them to suit

their needs:
    Suppose you are merging the "master" branch of another

    project located at /path/to/B (the repository does not have

    to be local but we use /path/to/B for the sake of

    simplicity) as a subdirectory "dir-B" in our project.  Here
This part looks like a half-updated WIP.
    ----------------

    $ git remote add -f Bproject /path/to/B <1>

    $ git merge -s ours --no-commit B/master <2>

    $ git read-tree --prefix=dir-B/ -u B/master <3>

    $ git commit -m "Merge B project as our subdirectory" <4>
    $ git pull -s subtree Bproject master <5>

    ----------------

    <1> name the other project "Bproject", and fetch.

    <2> prepare for the later step to record the result as a merge.

    <3> read "master" branch...
[ message continues ]

Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>

---
Here comes the 3rd try. I wonder if I should remove the mail header :) The

commands are from the mail, but the patch itself now are more based on the

suggestions by Junio (and reworded / reorganized).
Sorry for the late reply, I had some problem with my mail setup.
 Documentation/Makefile                    |    2 +-

 Documentation/howto/use-merge-subtree.txt |   71 +++++++++++++++++++++++++++++

 2 files changed, 72 insertions(+), 1 deletions(-)

 create mode 100644 Documentation/howto/use-merge-subtree.txt
diff --git a/Documentation/Makefile b/Documentation/Makefile

index 7b0685b..4addb8a 100644

--- a/Documentation/Makefile

+++ b/Documentation/Makefile

@@ -23,7 +23,7 @@ ARTICLES += everyday

 ARTICLES += git-tools

 ARTICLES += glossary

 # with their own formatting rules.

-SP_ARTICLES = howto/revert-branch-rebase user-manual

+SP_ARTICLES = howto/revert-branch-rebase howto/use-merge-subtree user-manual

 API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))

 SP_ARTICLES += $(API_DOCS)

 SP_ARTICLES += technical/api-index

diff --git a/Documentation/howto/use-merge-subtree.txt b/Documentation/howto/use-merge-subtree.txt

new file mode 100644

index 0000000..2f4f38a

--- /dev/null

+++ b/Documentation/howto/use-merge-subtree.txt

@@ -0,0 +1,71 @@

+Date: Sat, 5 Jan 2008 20:17:40 -0500

+From: Sean <seanlkml@sympatico.ca>

+To: Miklos Vajna <vmiklos@frugalware.org>

+Cc: git@vger.kernel.org

+Subject: Re: how to use git merge -s subtree?

+Abstract: In this article, Sean demonstrates how one can use the subtree merge

+ strategy.

+Message-ID: <BAYC1-PASMTP12374B54BA370A1E1C6E78AE4E0@CEZ.ICE>

+

+How to use the subtree merge strategy

+=====================================

+

+There are situations where you want to include contents in your project from an

+independently developed project. You can just pull from the other project as

...
[ message continues ]