diff options
author | Miklos Vajna <vmiklos@frugalware.org> | 2008-01-15 03:35:02 +0300 |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2008-01-15 05:04:51 +0300 |
commit | 471a5ce5dda5c4315fe0f1d5ad3c642fc1ff540c (patch) | |
tree | a0aacee8ef218169f1d526730cc457337a740b51 | |
parent | 11c57e6a9a0f31f970701a673adaa1826f502fa0 (diff) |
Add using merge subtree How-To
Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
-rw-r--r-- | Documentation/Makefile | 2 | ||||
-rw-r--r-- | Documentation/howto/using-merge-subtree.txt | 75 |
2 files changed, 76 insertions, 1 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 7b0685b7b2..7a325462ee 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/using-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/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt new file mode 100644 index 0000000000..0953a50b69 --- /dev/null +++ b/Documentation/howto/using-merge-subtree.txt @@ -0,0 +1,75 @@ +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 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 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 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 is the command sequence 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 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 + connects its history to yours, which can be something they don't want + to. |