Git 1.5.3 : submodule

Here’s another new functionality introduce in Git 1.5.3 : submodule.

Submodules allows you to manage subparts of a project in different git repositories and reference them in a “superproject” repository.

You can see it as an equivalent to Subversion “externals”.

A simple usage exemple (in your “superproject” root) :

git submodule add http://mygitdomain.tld/my_sub_project
git submodule init
git submodule update

1. This will add the remote my_sub_project as an entry in .gitmodules and a directory named my_sub_project in your “superproject”.
2. Then initialize all modules added, this means add them to .git/config
3. And finally clone and checkout the different modules in their respective directories (created by the git submodule add command)

[Update – 2007/12/05]

I forgot to add you should not work directly with the “superproject” git repository besides adding more submodules.

You should clone the “superproject” git repository first and then the submodule part will be usable.

git clone superproject superprojectcloned
cd superprojectcloned
git submodule init
git submodule update

and work from “superprojectcloned” repository.

Then when you want to include the last versions of the submodules, issue :

git submodule status
git submodule update

1. status, gives you an overview of the submodules state.
2. update, fetch the latest version and reference the sha1 associated.

5 comments »

1. 

   By peter 3 months later:

   
   

   There is no such command: “git update”

2. 

   By Jonathan Tron 3 months later:

   
   

   Peter : Oops you’re right, I’m correcting the mistakes.

3. 

   By Mark 7 months later:

   
   

   Thanks for this write-up.

4. 

   By Mark 7 months later:

   
   

   Hmmm, maybe things changed in 1.5.4.x, but when I do the initial git submodule add, I have to do a git commit before the changes will show up in cloned repositories.

5. 

   By peace 8 months later:

   
   

   For others trying to learn git: after git submodule update you should call git checkout master on those sub modules or else you will be working with a detached head and mess yourself up.