How to set up a git project to use an external repo submodule?

Question

I'd like to create a repo which pulls in a remote repo.

For example, let's say jQuery as a submodule:

git://github.com/jquery/jquery.git

What would be the process of creating a repo with jQuery as a submodule and adding my own external as a remote repo.

Also once this is setup, if I push / pull to my own remote, will the external remain intact?

Answer 1

1. You have a project -- call it MyWebApp that already has a github repo
2. You want to use the jquery repository in your project
3. You want to pull the jquery repo into your project as a submodule.

Submodules are really, really easy to reference and use. Assuming you already have MyWebApp set up as a repo, from terminal issue these commands:

cd MyWebApp
git submodule add git://github.com/jquery/jquery.git externals/jquery

This will create a directory named externals/jquery* and link it to the github jquery repository. Now we just need to init the submodule and clone the code to it:

git submodule update --init --recursive

You should now have all the latest code cloned into the submodule. If the jquery repo changes and you want to pull the latest code down, just issue the submodule update command again. Please note: I typically have a number of external repositories in my projects, so I always group the repos under an "externals" directory.

The online Pro Git Book has some good information on submodules (and git in general) presented in an easy-to-read fashion. Alternately, git help submodule will also give good information. Or take a look at the Git Submodule Tutorial on the git wiki.

I noticed this blog entry which talks about submodules and compares them to Subversion's svn:externals mechanism: http://speirs.org/blog/2009/5/11/understanding-git-submodules.html

_{* As a best practice, you should always place your submodules in their own directory, such as Externals. If you don't, your root project directory can become very cluttered very fast.}

Answer 2

Most of what you need to know has already been answered, so I won't bother addressing that, however, I've found a small piece of information that's usually missing.

As you know, "git pull" won't update the submodules, and "git submodules update" won't download the latest HEAD of those submodules either.

To update all of your submodules to their latest upstream revision, you can use

git submodule foreach git pull

If you often alter your submodules, and have lots of the, then "git foreach" will become invaluable.

Answer 3

I think that the @Hugo answer could be what you need and works fine. So I have found a easier way.

git submodule update --remote

That's all.

So a complete workflow could be:

git clone project-with-submodules
git submodule init
git config -l
git submodule update --remote