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

Miklos Vajna <vmiklos@frugalware.org> writes:

That's better.

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
    is the procedure to bootstrap and maintain such a layout.

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 of Bproject to the subdirectory "dir-B".
    <4> record the merge result.
    <5> maintain the result with subsequent merges using "subtree"
    
Then the discussion.

That's not incorrect, but I think we would need to discuss more important matters first. The discussion should consist of two parts.

First, the tips, tricks and caveats when using subtree merge.

 - The participant to your project may want to make changes
   pertaining to the subtree merged project independently and
   send the result upward, although it is not required (the
   other project can merge from your project using subtree --
   the subtree strategy can shift your tree up and let the other
   project merge only the parts of your tree that corresponds to
   it).

 - The other project may not choose to.  One possible reason not
   to is if it does not want to connect its history to yours
   (although you wanted to do so in your repository).

And comparison with an alternative, "submodules":

 - It is simpler to merge another project using subtree than
   treating the other project as "submodule", due to less
   management hassles (pro).

 - It ties the two histories together as equals.  If the other
   project chooses to also use subtree merge from you, the two
   histories will be tied very closely, which often is not
   desirable from the point of view of the "contained" project
   (con).

 - It does not allow "narrow checkout" and "narrow clone" as
   submodule does (con).

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