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.

Sat, 15 Sep 2007 21:31 Posted in

  1. By peter 04/12/2007 at 15h38

    There is no such command: “git update”

  2. By Jonathan Tron 05/12/2007 at 08h56

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

  3. By Mark 13/04/2008 at 08h07

    Thanks for this write-up.

  4. By Mark 13/04/2008 at 18h17

    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 05/05/2008 at 19h05

    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.

Comment Git 1.5.3 : submodule