Git clone vs Git submodule

Having recently made the switch from svn to git, I wanted to achieve what svn externals did (and what Piston did better). Turns out this is pretty simple, for example to get rails on edge:

cd your_git_dir
git submodule add git://github.com/rails/rails.git vendor/rails
cd your_git_dir
git submodule add git://github.com/rails/rails.git vendor/rails

A couple of other default submodules you'll want:

git submodule add git://github.com/dchelimsky/rspec.git vendorpluginsrspec
git submodule add git://github.com/dchelimsky/rspec-rails.git vendorpluginsrspec-rails
git submodule add git://github.com/dchelimsky/rspec.git vendorpluginsrspec
git submodule add git://github.com/dchelimsky/rspec-rails.git vendorpluginsrspec-rails

What submodule does is to check out the submodules as their own repositories, so they are tracked independently of the repository you made them submodules of. The submodules you have are tracked in the .gitmodules file, which might look something like this:

[submodule "vendorrails"]
path = vendor/rails
url = git://github.com/rails/rails.git
[submodule "vendor/plugins/rspec"]
path = vendor/plugins/rspec
url = git://github.com/dchelimsky/rspec.git
[submodule "vendor/plugins/rspec-rails"]
path = vendor/plugins/rspec-rails
url = git://github.com/dchelimsky/rspec-rails.git
[submodule "vendorrails"]
path = vendor/rails
url = git://github.com/rails/rails.git
[submodule "vendor/plugins/rspec"]
path = vendor/plugins/rspec
url = git://github.com/dchelimsky/rspec.git
[submodule "vendor/plugins/rspec-rails"]
path = vendor/plugins/rspec-rails
url = git://github.com/dchelimsky/rspec-rails.git

Or at least that's how it should look, Windows seems to mess this up into looking something like the following:

[submodule "vendorrails"]
path = vendor\rails
[submodule "vendorrails"]
url = git://github.com/rails/rails.git
[submodule "vendorpluginsrspec"]
path = vendor\plugins\rspec
[submodule "vendorpluginsrspec"]
url = git://github.com/dchelimsky/rspec.git
[submodule "vendorpluginsrspec-rails"]
path = vendor\plugins\rspec-rails
[submodule "vendorpluginsrspec-rails"]
url = git://github.com/dchelimsky/rspec-rails.git
[submodule "vendorrails"]
path = vendor\rails
[submodule "vendorrails"]
url = git://github.com/rails/rails.git
[submodule "vendorpluginsrspec"]
path = vendor\plugins\rspec
[submodule "vendorpluginsrspec"]
url = git://github.com/dchelimsky/rspec.git
[submodule "vendorpluginsrspec-rails"]
path = vendor\plugins\rspec-rails
[submodule "vendorpluginsrspec-rails"]
url = git://github.com/dchelimsky/rspec-rails.git

Note especially that you need to remove the 's and replace all 's with /'s. If you don't git will give a fail message like:

fatal: bad config file line 2 in .gitmodules
No submodule mapping found in .gitmodules for path 'vendor/plugins/attachment_fu'
fatal: bad config file line 2 in .gitmodules
No submodule mapping found in .gitmodules for path 'vendor/plugins/attachment_fu'

I don't know why it's doing that, maybe it's something I'm doing wrong but you'll need to tidy it up to make it look more like the first example in order for it to work properly.

One final thing to be aware of is that when you clone onto a new machine you'll need to run the following commands:

git submodule init
git submodule update
git submodule init
git submodule update

This will initialise the submodules that are referenced in the .gitmodules file, then pull them down. By default cloning doesn't seem to do that.

Share Post:

What to Read Next

For a deeper understanding of common Git issues, the post When Git tells you it failed to push some refs offers insights into resolving the "non-fast forward" error. Additionally, you might find git: what to do if you commit to no branch helpful as it addresses handling the "detached HEAD" state in Git, frequently encountered when working with submodules.