Git: How to clone a 3rd party library into a subdirectory of my app's repository?

I'm trying to figure out the proper way to clone a 3rd party library (engage.iphone from Janrain) into my own app's directo开发者_开发技巧ry structure in a way that will let me pull the latest changes and merge them with any changes that I make locally. I also want the 3rd party library (merged with my changes) to be included in the git repo for my own app when I push it.

Structure would be something like this:

myApp/  <- this is my app, which is its own git repo
    external/
        engage.iphone/ <- this is the 3rd party library I want to keep up-to-date
    mySource1.h
    mySource2.m
    ...

How can I set it up this way safely? Is there any special process for merging later on down the road, after it's been set up?

Submodules are the easiest way to accomplish this.

There are two common ways of working with submodules - adding new ones and initialising existing ones.

Adding New Submodules

From the root of your local repository run:

git submodule add <repository> external/engage.iphone.

The add command is for when you're initially adding a submodule to the repository, as opposed to when you've cloned a repository with existing submodules). It adds another repository which can be on a local or remote path (remember that other developers need access to this if you publish your repository!) to the .gitmodules file in your repository root, then clones the repository into the location you specified; external/engage.iphone in the above example. At this stage you have the sub-repository files on your system and it is listed as a submodule in both the .gitmodules file, your local repositories' config.

However you might not be adding the submodules yourself...

Initialising Existing Submodules

Things change a bit if you're cloning a repository that already has submodules added to it. In this situation the .gitmodules file will have the submodules listed in it with locations to retrieve them from, but your local repository config knows nothing about them and the actual files don't yet exist on your system. First you need to initialise the submodules:

git submodule init

This will run through any repositories listed in your .gitmodules and add them to your .git/config. Git now knows about the repository but it hasn't actually cloned it yet, so run:

git submodule update

You can run this command anytime to update the registered submodules, i.e. clone missing ones.

git submodule sync <submodule>

Run this to update all submodules to their remote HEAD, unless you specified a specific commit when you did the submodule add! Specifying a specific submodule will only sync that one.

In true git fashion the init command can be combined with the update to save time:

git submodule update --init.

Of course, you can always manually update your .gitmodules and .git/config once you've learnt the layout they use (similar to branch and remote sections in the config).

All the specifics can be found in the man page (kernel.org version).