threads / patch / 8093

patchDocument subproject feature

Subject: [PATCH] Document subproject feature

## tl;dr

3 messages between May 12, 2007 and May 12, 2007. Diffs are folded; open one to read it.

replies: 2people: 3as markdown or json

Amos Waterland· May 12, 2007, 00:58 UTC · lore

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(-)
Show changes to Documentation/user-manual.txt +34 −1
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
 ---------------
Junio C Hamano· May 12, 2007, 20:42 UTC · re: Amos Waterland · lore

Re: [PATCH] Document subproject feature

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

Show 8 quoted lines
> 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.

Show 16 quoted lines
> +[[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.

J. Bruce Fields· May 12, 2007, 23:18 UTC · re: Amos Waterland · lore

Re: [PATCH] Document subproject feature

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.

← back to recent threads