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.

Footnotes

1. ^ 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.