Git repository inside another git repository

Question

I have the following directories structure:

• g1/
  • .git
  • a
  • b
  • c/

Answer 1

Submodules (discussed in the Pro Git Book), helps manage repositories nested within a main repository:

Submodules allow foreign repositories to be embedded within a dedicated subdirectory of the source tree, always pointed at a particular commit.

They are not to be confused with remotes, which are meant mainly for branches of the same project; submodules are meant for different projects you would like to make part of your source tree, while the history of the two projects still stays completely independent and you cannot modify the contents of the submodule from within the main project.

Submodules maintain their own identity; the submodule support just stores the submodule repository location and commit ID, so other developers who clone the superproject can easily clone all the submodules at the same revision.

Answer 2

Git 2.5+ (Q2 2015) will be a bit more precise in how it present submodule.
Since a submodule is registered as a gitlink (a special entry in the index), that explains why 'c' is empty when the parent repo is cloned.
See also "git submodule checks out the same commit".
You need a git submodule update --init to fill-up 'c'.

That is now more clearly documented.

See commit ec48a76 (27 May 2015) by Stefan Beller (stefanbeller).
^{(Merged by Junio C Hamano -- gitster -- in commit 7df5c97, 11 Jun 2015)}

submodule doc: reorder introductory paragraphs

It's better to start the man page with a description of what submodules actually are, instead of saying what they are not.

The git submodule man page now (June 2015) starts with:

A submodule allows you to keep another Git repository in a subdirectory of your repository.
The other repository has its own history, which does not interfere with the history of the current repository.
This can be used to have external dependencies such as third party libraries for example.

When cloning or pulling a repository containing submodules however, these will not be checked out by default; the 'init' and 'update' subcommands will maintain submodules checked out and at appropriate revision in your working tree.