Git/Submodules and Superprojects

A superproject is a new aspect of git which has been in development for a long while. It addresses the need for better control over numerous git repositories. The porcelain for the superproject functionality is fairly new and was only recently released with Git v1.5.3.

A Git superproject may consist of a set of git repositories and each of these "git repositories" is called a submodule.You can think of a submodule as a subproject, and the superproject as a supermodule. It really doesn't make too much sense why either of these terms would have a sub- or super- prefix without their alternative; nonetheless, that's how the official Git documentation will refer to them.

The only git application specific to the submodule/superproject functionality is git-submodule.

Superprojects

A Superproject, is simply a git repository. To create a superproject, simply git init any directory, and git submodule add all of the git archives you wish to include. A quick aside, you can not currently git submodule add git repositories that are direct children within the same directory.^[1]

The resulting structure will look similar to this:

|- superproject
  |- submodule (git archive) [a]
  |- submodule [b]
  |- submodule [c]
  |- submodule [d]

When someone pulls down the superproject, they will see a series of empty folders for each submodule. They can then git submodule init all of those that they wish to utilize.

Submodules

A git archive is said to become a submodule the second after you execute git submodule add in another git repository.

Work Flow

The work flow of superprojects, and submodules should generally adhere to the following:

Make change in submodule
git commit change in submodule
git commit change in superproject
git submodule update to push change to the individual repositories that predate the superproject.

Footnotes

^ Well that isn't true at all, Git supports this as of v1.5.3, but the official porcelain doesn't. You can git init a parent directory, and create your own ".gitmodules", then follow it up with a git submodule init. Generally speaking though, what the porcelain doesn't cover is outside of the scope of this book.

[1]