How to nest git repositories; fetch and merge

Question

So I have two git repos. The first is our framework (think db abstraction, functions) and then another git repo for our new project.

I want to include the framework git repo into the project git, and according to GitHub Help, this should work:

 cd /project
 git remote add framework git://github.com/username/Framework.git
 git fetch framework
 git merge framework/master

The problem is, when I do the merge, it brings everything all files from framework and simply dumps them into the root of project. Instead, how can we have framework files merged into a child directory like /project/framework/?

Answer 1

You may want to look into Git's submodule support. A submodule lets you embed one git repository inside another git repository. There are alternative solutions to this sort of thing, but I haven't used them myself.

An example might look like this:

$ git clone git://github.com/username/project.git
$ cd project
$ git submodule add git://github.com/username/framework.git framework
$ git commit -m "added framework submodule"

If you are cloning a repository with submodules, you need to use the --recursive option:

$ git clone --recursive git://<repository-with-submodules>.git

Or alternatively, you can clone regularly and then run:

$ git submodule init
$ git submodule update

Read the linked document (and git submodule --help) for more information.

If changes are made to the submodule, you bring them in like this:

# first update the submodule just like any other git repository
$ cd project/framework
$ git pull

# now you have to record the new commit in the parent repository
$ cd ..
$ git commit -m "updated framework submodule"

The last step is necessary because git keeps a record of the specific commit associated with a given submodule (so that when anyone clones the parent they'll get that version of the submodule, rather than its most up-to-date revision, which could have undergone breaking changes that would prevent it to work as intended with the parent repository). So if you update the submodule, you need to record the new commit in the parent.

If you make changes within the framework submodule, you would again just git push them like you would with any other repository. You would then have to commit the new revision in the parent module.