How to use the subtree merge strategy

From 0e47b23874132a7fffde3f56c7c4f13c1f0b8cc4 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 15 Jan 2008 08:31:10 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.5.4-rc3-11-g4e67 --- config.txt | 4 +- git-config.html | 6 +- git-rerere.html | 11 +- git-rerere.txt | 4 + howto-index.html | 9 +- howto-index.txt | 6 + howto/using-merge-subtree.html | 372 +++++++++++++++++++++++++++++++++ howto/using-merge-subtree.txt | 75 +++++++ 8 files changed, 480 insertions(+), 7 deletions(-) create mode 100644 howto/using-merge-subtree.html create mode 100644 howto/using-merge-subtree.txt diff --git a/config.txt b/config.txt index df091d1b8..877eda960 100644 --- a/config.txt +++ b/config.txt @@ -543,8 +543,8 @@ rerere.enabled:: Activate recording of resolved conflicts, so that identical conflict hunks can be resolved automatically, should they be encountered again. linkgit:git-rerere[1] command is by - default enabled, but can be disabled by setting this option to - false. + default enabled if you create `rr-cache` directory under + `$GIT_DIR`, but can be disabled by setting this option to false. gitcvs.enabled:: Whether the CVS server interface is enabled for this repository. diff --git a/git-config.html b/git-config.html index 61e1f4a51..745cd72a3 100644 --- a/git-config.html +++ b/git-config.html @@ -1522,8 +1522,8 @@ rerere.enabled Activate recording of resolved conflicts, so that identical conflict hunks can be resolved automatically, should they be encountered again. git-rerere(1) command is by - default enabled, but can be disabled by setting this option to - false. + default enabled if you create rr-cache directory under + $GIT_DIR, but can be disabled by setting this option to false.

@@ -2203,7 +2203,7 @@ web.browser diff --git a/git-rerere.html b/git-rerere.html index 80f498aa8..a380aa3c0 100644 --- a/git-rerere.html +++ b/git-rerere.html @@ -284,6 +284,15 @@ to the "release" branch, or sent out and accepted upstream).

automerge results and corresponding hand-resolve results on the initial manual merge, and later by noticing the same automerge results and applying the previously recorded hand resolution.

+ + + +

Note

You need to set the configuration variable rerere.enabled to +enable this command.

COMMANDS

@@ -472,7 +481,7 @@ conflict.

diff --git a/git-rerere.txt b/git-rerere.txt index 3793267da..a53858e25 100644 --- a/git-rerere.txt +++ b/git-rerere.txt @@ -22,6 +22,10 @@ automerge results and corresponding hand-resolve results on the initial manual merge, and later by noticing the same automerge results and applying the previously recorded hand resolution. +[NOTE] +You need to set the configuration variable rerere.enabled to +enable this command. + COMMANDS -------- diff --git a/howto-index.html b/howto-index.html index 7d73162cb..60318f789 100644 --- a/howto-index.html +++ b/howto-index.html @@ -356,12 +356,19 @@ into which branch and who can make a tag.

use-git-daemon

+using-merge-subtree by Sean <seanlkml@sympatico.ca> +

In this article, Sean demonstrates how one can use the subtree merge +strategy.

diff --git a/howto-index.txt b/howto-index.txt index 351093c24..20ce40ba6 100644 --- a/howto-index.txt +++ b/howto-index.txt @@ -68,3 +68,9 @@ into which branch and who can make a tag. +* link:howto/using-merge-subtree.html[using-merge-subtree] by Sean + +In this article, Sean demonstrates how one can use the subtree merge +strategy. + + diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html new file mode 100644 index 000000000..b568a81c4 --- /dev/null +++ b/howto/using-merge-subtree.html @@ -0,0 +1,372 @@ + + + + + + +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)

+
+name the other project "Bproject", and fetch. +
+
+
+prepare for the later step to record the result as a merge. +
+
+
+read "master" branch of Bproject to the subdirectory "dir-B". +
+
+
+record the merge result. +
+
+
+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. +
+

+ + + diff --git a/howto/using-merge-subtree.txt b/howto/using-merge-subtree.txt new file mode 100644 index 000000000..0953a50b6 --- /dev/null +++ b/howto/using-merge-subtree.txt @@ -0,0 +1,75 @@ +Date: Sat, 5 Jan 2008 20:17:40 -0500 +From: Sean +To: Miklos Vajna +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: + +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. -- 2.26.2