Re: [PATCH] user-manual: Explain what submodules are good for.

On Sun, Sep 23, 2007 at 11:14:09PM -0400, Michael Smith wrote:

Rework the introduction to the Submodules section to explain why
someone would use them, and fix up submodule references from the
tree-object and todo sections.

Thanks!

+Some large projects are composed of smaller, self-contained parts.  For
+example, an embedded Linux distribution's source tree would include every
+piece of software in the distribution; a movie player might need to build
+against a specific, known-working version of a decompression library;
+several independent programs might all share the same build scripts.

...

+Git's submodule support allows a repository to contain, as a subdirectory, a
+checkout of an external 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.  The gitlink:git-submodule[1]
+command manages submodules.

That looks helpful, thanks, but a little more detail might be nice.

Imagining myself as a reader trying to decide whether to use submodules
in a given case, I'm not sure this would tell me everything I need to
know.  For example, how does this compare to just importing a snapshot
of the library into your tree?  (Or possibly using the subtree merge
strategy?)

Some issues that pop to mind are scalability (when does a monolithic
tree get too large to work with?) and backwards compatibility (what
version does everybody working on your project need to have for it to
work?  What problems will you see if a few people are stuck with an
older git?)  I haven't followed submodule development, though, so may
have missed more important issues.

--b.