227

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?

memmons
  • 40,222
  • 21
  • 149
  • 183
Tom
  • 33,626
  • 31
  • 85
  • 109
  • 1
    When you say "pull in" are you saying you want the jQuery repo to be a submodule of your own repo? – ezod Jan 26 '10 at 17:02
  • Yes exactly, sorry if that's not clear. I'd like to know how I set this up as an external while pushing and pulling changes to my own remote – Tom Jan 26 '10 at 19:43
  • See the [Git Submodule Tutorial](https://git.wiki.kernel.org/index.php/GitSubmoduleTutorial) on the git wiki. – Greg Bacon Aug 04 '15 at 13:49

4 Answers4

364
  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.

memmons
  • 40,222
  • 21
  • 149
  • 183
  • 4
    Great explanation! :) Also, "git help submodules" helps if you want a bit more details, internals, etc. – WhyNotHugo Feb 29 '12 at 05:35
  • Just to clarify, if I need jQuery on a project I have on Github, would it be better to add jQuery as a submodule? – aurbano Jan 19 '13 at 12:35
  • 1
    @Chevi It depends on your requirements. In general, adding a git project as a submodule to your project is a good solution for projects that change often or are still in development. This allows you to easily ensure that all 3rd party code in your project is up to date. For 3rd party code that is essentially static -- stable, mature code that probably won't change much from version-to-version -- using a submodule doesn't provide much value. – memmons Feb 17 '13 at 22:05
  • 2
    sorry but compared to svn externals, it is not that easy – Keil Mar 12 '13 at 00:50
  • 2
    @Keil It's two commands, `git submodule add` and `git submodule update`...I'm not sure how much easier it could get. – memmons Dec 06 '13 at 03:00
  • 1
    @MichaelG.Emmons Here's how: When you update with subversion, you don't even have to run the second command, you just do "svn update" on the main project and all externals update automatically. – Hakanai Mar 14 '14 at 04:30
  • @MichaelG.Emmons Git submodules are a very useful tool, but his use has important implications and has to be very carefully considered, see for example [The problem with Git Submodules](http://ayende.com/blog/4746/the-problem-with-git-submodules). – DaniCE Sep 03 '14 at 18:50
  • @DaniCE Submodules fit a specific niche and can be useful, but I typically use [CocoaPods](http://cocoapods.org/) for dependency management. – memmons Sep 03 '14 at 21:06
  • In .Net the usual recommendation is to use Nuget for required libraries / projects... – DaniCE Sep 03 '14 at 21:47
  • And in typical Git fashion, these instructions don't work. Leave it to Git to take a simple task, and make it difficult to impossible. – jww Nov 01 '17 at 15:03
28

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.

WhyNotHugo
  • 9,423
  • 6
  • 62
  • 70
3

In the end I found http://github.com/evilchelu/braid it seemed to fit with how I expected submodules and remotes to work

Tom
  • 33,626
  • 31
  • 85
  • 109
1

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
Dapaldo
  • 301
  • 1
  • 3
  • 8