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.

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:
 * 1) Make change in submodule
 * 2) git commit change in submodule
 * 3) git commit change in superproject
 * 4) git submodule update to push change to the individual repositories that predate the superproject.