[PATCH] Document subproject feature

[PATCH] Document subproject feature

[Amos Waterland]

Add a section to the user manual about the new subproject support.
Show how to make a subproject.

Signed-off-by: Amos Waterland <apw@us.ibm.com>

---

 user-manual.txt |   35 ++++++++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 13db969..27d601f 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1,4 +1,4 @@
-Git User's Manual (for version 1.5.1 or newer)
+Git User's Manual (for version 1.5.2 or newer)
 ______________________________________________
 
 This manual is designed to be readable by someone with basic unix
@@ -1406,6 +1406,39 @@ just performs a "fast forward"; the head of the current branch is moved
 forward to point at the head of the merged-in branch, without any new
 commits being created.
 
+[[subprojects]]
+Subprojects
+-----------
+
+Some large development efforts, such as embedded Linux distributions,
+are composed of a set of large projects, each with its own development
+team, but all of which are combined to produce the project as a whole.
+For example, there might be a firmware project, a hypervisor project,
+a kernel project, and a userspace project.  Note that while each
+project is conceptually independent, there are many cases in which a
+change to the hypervisor necessitates a change to the kernel, for
+example.
+
+In this case it is nice to be able to reason about the state of the
+entire project, but also not inconvenience each development team with
+checking out a gigantic repository that represents the entire project.
+Git provides subproject support for this case, which is similar to CVS
+modules or the hg forest extension.
+
+Here is an example of creating a subproject inside an existing project:
+
+-------------------------------------------------
+$ mkdir subproject
+$ cd subproject
+$ git init
+$ touch Makefile
+$ git add Makefile
+$ git commit -m "Create subproject."
+$ cd ..
+$ git add subproject
+$ git commit -m "Add subproject."
+-------------------------------------------------
+
 [[fixing-mistakes]]
 Fixing mistakes
 ---------------

Re: [PATCH] Document subproject feature

[Junio C Hamano]

apw@us.ibm.com (Amos Waterland) writes:

> Add a section to the user manual about the new subproject support.
> Show how to make a subproject.
>
> Signed-off-by: Amos Waterland <apw@us.ibm.com>

I like the idea of having new things described in the
user manual for the new release, but with a few reservations...

> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 13db969..27d601f 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1,4 +1,4 @@
> -Git User's Manual (for version 1.5.1 or newer)
> +Git User's Manual (for version 1.5.2 or newer)
>  ______________________________________________

Another option is to leave this as is, and make a note on the
subproject and gitattributes section that they apply only to
1.5.2 or later.  I am debating myself which one is better.

> +[[subprojects]]
> +Subprojects
> +-----------
> +
> +Some large development efforts, such as embedded Linux distributions,
> +are composed of a set of large projects, each with its own development
> +team, but all of which are combined to produce the project as a whole.
> +For example, there might be a firmware project, a hypervisor project,
> +a kernel project, and a userspace project.  Note that while each
> +project is conceptually independent, there are many cases in which a
> +change to the hypervisor necessitates a change to the kernel, for
> +example.
>
> +In this case it is nice to be able to reason about the state of the
> +entire project, but also not inconvenience each development team with
> +checking out a gigantic repository that represents the entire project.

The above makes it sound as if the primary use case is to
artificially split a project that is otherwise a coherent whole,
only because split makes each piece smaller and more manageable
to handle.  While that use case is also in scope, I do not think
that is the primary one.  The above description sends a wrong
message, IMHO.

The intent of the current design of the subproject support is
more to keep track of 'subprojects' that are _not_ under your
control.  For example, an embeddd Linux appliance developer does
not control the kernel project, nor glibc, nor busybox.  He just
integrates the work by these other projects, which do not
particularly care during their own development about how _he_ is
fitting things together.

The developer however is in total control of how to fit these
pieces together, along with his own userspace, to build his
product.  He uses the subproject feature to bind these external
projects into his own project, and freeze the HEAD version for
these subprojects to match the appliance's own needs ("we will
use this version of kernel together with that version of the
out-of-tree driver").  The "embedded distribution" example you
gave matches this use case better.

Re: [PATCH] Document subproject feature

[J. Bruce Fields]

On Fri, May 11, 2007 at 08:58:44PM -0400, Amos Waterland wrote:
> Add a section to the user manual about the new subproject support.
> Show how to make a subproject.

Looks like a great idea.  It'll be nice to fill this out with some
details--http://marc.info/?l=git&m=117885769320212&w=2 might provide
some starting points.

--b.