FM / howto

/usr/share/doc/git/howto

Name	Size	Mode	Actions
coordinate-embargoed-releases.html	29838	0644	edit dl rm
coordinate-embargoed-releases.txt	10823	0644	edit dl rm
keep-canonical-history-correct.html	26249	0644	edit dl rm
keep-canonical-history-correct.txt	6795	0644	edit dl rm
maintain-git.html	41732	0644	edit dl rm
maintain-git.txt	18220	0644	edit dl rm
new-command.html	22001	0644	edit dl rm
new-command.txt	4460	0644	edit dl rm
rebase-from-internal-branch.html	24456	0644	edit dl rm
rebase-from-internal-branch.txt	6310	0644	edit dl rm
rebuild-from-update-hook.html	20387	0644	edit dl rm
rebuild-from-update-hook.txt	3137	0644	edit dl rm
recover-corrupted-blob-object.html	23884	0644	edit dl rm
recover-corrupted-blob-object.txt	5510	0644	edit dl rm
recover-corrupted-object-harder.html	36038	0644	edit dl rm
recover-corrupted-object-harder.txt	14607	0644	edit dl rm
revert-a-faulty-merge.html	30865	0644	edit dl rm
revert-a-faulty-merge.txt	10856	0644	edit dl rm
revert-branch-rebase.html	24740	0644	edit dl rm
revert-branch-rebase.txt	7823	0644	edit dl rm
separating-topic-branches.html	20526	0644	edit dl rm
separating-topic-branches.txt	3356	0644	edit dl rm
setup-git-server-over-http.html	30562	0644	edit dl rm
setup-git-server-over-http.txt	8613	0644	edit dl rm
update-hook-example.html	23272	0644	edit dl rm
update-hook-example.txt	6289	0644	edit dl rm
use-git-daemon.html	19649	0644	edit dl rm
use-git-daemon.txt	2135	0644	edit dl rm
using-merge-subtree.html	20235	0644	edit dl rm
using-merge-subtree.txt	3025	0644	edit dl rm
using-signed-tag-in-pull-request.html	26765	0644	edit dl rm
using-signed-tag-in-pull-request.txt	8282	0644	edit dl rm

Edit: /usr/share/doc/git/howto/using-merge-subtree.txt (3025B)

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: how to use git merge -s subtree?
Abstract: In this article, Sean demonstrates how one can use the subtree merge
 strategy.
Content-type: text/asciidoc
Message-ID: <BAYC1-PASMTP12374B54BA370A1E1C6E78AE4E0@CEZ.ICE>

How to use the subtree merge strategy
=====================================

There are situations where you want to include content 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 to.  A better solution for this
problem can be to merge the project as 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 a 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 is the command sequence you need:

----------------
$ git remote add -f Bproject /path/to/B <1>
$ git merge -s ours --no-commit --allow-unrelated-histories 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 used for the initial merge, while the last
one is to merge updates from 'B project'.

Comparing 'subtree' merge with submodules
-----------------------------------------

- The benefit of using subtree merge is that it requires less
  administrative burden 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
  connect its history to yours, which can be something they don't want
  to.

cmd: