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.

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.