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

From: J. Bruce Fields <bfields@fieldses.org>
Date: Sep 24, 2007, 21:33 UTC
Message-ID: <20070924213342.GL26387@fieldses.org>
In-Reply-To: <11906036491118-git-send-email-msmith@cbnco.com>

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!

Show 5 quoted lines

> +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.

...

Show 6 quoted lines

> +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.