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

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

[Junio C Hamano]

Miklos Vajna <vmiklos@frugalware.org> writes:

> here is an updated version. i added a section (before the commands) to
> describe the workflow where the subtree merge strategy can be useful. i
> also added a section at the end where i mention submodules.

That's better.

> @@ -0,0 +1,48 @@
> +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
> +=====================================
> +
> +The merge strategy 'subtree' is a slightly modified 'recursive'.  It merges
> +current branch A with other branch B using common merge base O (and if there
> +are more than one common merge bases, they are recursively merged), but it can
> +"shift" trees while doing so.
> +
> +This can be handy if you want to merge a branch to a subdirectory, for example
> +git has the git-gui master branch in its git-gui/ subdirectory.
> +
> +So the target is to merge a branch of repo B to a subdirectory of the current
> +branch.
> +
> +You need the followings steps to perform the master branch of B to the
> +subdirectory B/ for the first merge:

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.

> +----
> +$ 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>
> +$ git pull -s subtree B master <5>
> +----
> +<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 the above four steps once, after that you can keep doing:
> +
> +----
> +$ git pull -s subtree B master
> +----

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.

> +The benefit of the subtree merge strategy over submodules is that submodules
> +were not always available and it may still make sense to avoid it today,
> +because use of a submodule in a repository makes the repository
> +non-interoperable with any clients older than 1.5.2 series.

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).

[PATCH] Add [HOWTO] using merge subtree.

[Miklos Vajna]

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
+long as there are no conflicting paths.
+
+The problematic case is when there are conflicting files. Potential candidates
+are Makefiles and other standard filenames. You could merge these files but
+probably you do not want.  A better solution for this problem can be to merge
+the project to its own subdirectory. This is not supported by the 'recursive'
+merge strategy, so just pulling won't work.
+
+What you want is the 'subtree' merge strategy, which helps you in such a
+situation.
+
+In this example, let's say you have the repository at `/path/to/B` (but it can
+be an URL as well, if you want). You want to merge the 'master' branch of that
+repository to the `dir-B` subdirectory in your current branch.
+
+Here are all the commands you need:
+
+----------------
+$ git remote add -f Bproject /path/to/B <1>
+$ git merge -s ours --no-commit Bproject/master <2>
+$ git read-tree --prefix=dir-B/ -u Bproject/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"
+
+The first four commands are necessary for the initial merge, while the last one
+should be used to merge updates from 'B project'.
+
+Comparing 'subtree' merge with submodules
+-----------------------------------------
+
+- The benefit of using subtree merge is that it requires less attention from
+  the users of your repository. It works with older (before Git v1.5.2) clients
+  and you have the code right after clone.
+
+- However if you use submodules then you can choose not to transfer the
+  submodule objects. This may be a problem with the subtree merge.
+
+- Also, in case you make changes to the other project, it is easier to submit
+  changes if you just use submodules.
+
+Additional tips
+---------------
+
+- If you made changes to the other project in your repository, they may want to
+  merge from your project. This is possible using subtree -- it can shift up
+  the paths in your tree and then they can merge only the relevant parts of
+  your tree.
+
+- Please note that if the other project merges from you, then it will connects
+  its history to yours, which can be something they don't want to.
-- 
1.5.4.rc2-dirty

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

[Junio C Hamano]

Miklos Vajna <vmiklos@frugalware.org> 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: <BAYC1-PASMTP12374B54BA370A1E1C6E78AE4E0@CEZ.ICE>
> +
> +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'".

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Miklos Vajna <vmiklos@frugalware.org> 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: <BAYC1-PASMTP12374B54BA370A1E1C6E78AE4E0@CEZ.ICE>
>> +
>> +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.

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> 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.