summaryrefslogtreecommitdiff
path: root/Documentation/howto/using-merge-subtree.txt
diff options
context:
space:
mode:
authorLibravatar Junio C Hamano <gitster@pobox.com>2010-01-30 16:03:10 -0800
committerLibravatar Junio C Hamano <gitster@pobox.com>2010-01-30 16:03:10 -0800
commit00d3278c8534a8244ae3447189401111e017fd5d (patch)
treef1c19903bc10ffe4816642040080fb6cfd5da376 /Documentation/howto/using-merge-subtree.txt
parentt6000lib: Fix permission (diff)
parentAdd a small patch-mode testing library (diff)
downloadtgif-00d3278c8534a8244ae3447189401111e017fd5d.tar.xz
Merge commit 'b319ef7' into jc/maint-fix-test-perm
* commit 'b319ef7': (8132 commits) Add a small patch-mode testing library git-apply--interactive: Refactor patch mode code t8005: Nobody writes Russian in shift_jis Fix severe breakage in "git-apply --whitespace=fix" Update release notes for 1.6.4 After renaming a section, print any trailing variable definitions Make section_name_match start on '[', and return the length on success send-email: detect cycles in alias expansion Show the presence of untracked files in the bash prompt. SunOS grep does not understand -C<n> nor -e Fix export_marks() error handling. git repack: keep commits hidden by a graft Add a test showing that 'git repack' throws away grafted-away parents git branch: clean up detached branch handling git branch: avoid unnecessary object lookups git branch: fix performance problem git svn: fix shallow clone when upstream revision is too new do_one_ref(): null_sha1 check is not about broken ref configure.ac: properly unset NEEDS_SSL_WITH_CRYPTO when sha1 func is missing janitor: useless checks before free ...
Diffstat (limited to 'Documentation/howto/using-merge-subtree.txt')
-rw-r--r--Documentation/howto/using-merge-subtree.txt75
1 files changed, 75 insertions, 0 deletions
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.