{"thread":{"id":"8093","subject":"[PATCH] Document subproject feature","startedAt":"2007-05-12T00:58:44Z","lastAt":"2007-05-12T23:18:02Z","messageCount":3,"participants":["Amos Waterland","Junio C Hamano","J. Bruce Fields"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"41880","messageId":"20070512005844.GA24184@us.ibm.com","threadId":"8093","inReplyTo":null,"subject":"[PATCH] Document subproject feature","fromName":"Amos Waterland","fromEmail":"apw@us.ibm.com","sentAt":"2007-05-12T00:58:44Z","receivedAt":"2007-05-12T00:58:44Z","isPatch":true,"sender":{"key":"apw@debian.org","avatar":null},"body":"Add a section to the user manual about the new subproject support.\nShow how to make a subproject.\n\nSigned-off-by: Amos Waterland <apw@us.ibm.com>\n\n---\n\n user-manual.txt |   35 ++++++++++++++++++++++++++++++++++-\n 1 file changed, 34 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 13db969..27d601f 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1,4 +1,4 @@\n-Git User's Manual (for version 1.5.1 or newer)\n+Git User's Manual (for version 1.5.2 or newer)\n ______________________________________________\n \n This manual is designed to be readable by someone with basic unix\n@@ -1406,6 +1406,39 @@ just performs a \"fast forward\"; the head of the current branch is moved\n forward to point at the head of the merged-in branch, without any new\n commits being created.\n \n+[[subprojects]]\n+Subprojects\n+-----------\n+\n+Some large development efforts, such as embedded Linux distributions,\n+are composed of a set of large projects, each with its own development\n+team, but all of which are combined to produce the project as a whole.\n+For example, there might be a firmware project, a hypervisor project,\n+a kernel project, and a userspace project.  Note that while each\n+project is conceptually independent, there are many cases in which a\n+change to the hypervisor necessitates a change to the kernel, for\n+example.\n+\n+In this case it is nice to be able to reason about the state of the\n+entire project, but also not inconvenience each development team with\n+checking out a gigantic repository that represents the entire project.\n+Git provides subproject support for this case, which is similar to CVS\n+modules or the hg forest extension.\n+\n+Here is an example of creating a subproject inside an existing project:\n+\n+-------------------------------------------------\n+$ mkdir subproject\n+$ cd subproject\n+$ git init\n+$ touch Makefile\n+$ git add Makefile\n+$ git commit -m \"Create subproject.\"\n+$ cd ..\n+$ git add subproject\n+$ git commit -m \"Add subproject.\"\n+-------------------------------------------------\n+\n [[fixing-mistakes]]\n Fixing mistakes\n ---------------\n"},{"id":"41967","messageId":"7vlkftwz71.fsf@assigned-by-dhcp.cox.net","threadId":"8093","inReplyTo":"20070512005844.GA24184@us.ibm.com","subject":"Re: [PATCH] Document subproject feature","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-05-12T20:42:58Z","receivedAt":"2007-05-12T20:42:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"apw@us.ibm.com (Amos Waterland) writes:\n\n> Add a section to the user manual about the new subproject support.\n> Show how to make a subproject.\n>\n> Signed-off-by: Amos Waterland <apw@us.ibm.com>\n\nI like the idea of having new things described in the\nuser manual for the new release, but with a few reservations...\n\n> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> index 13db969..27d601f 100644\n> --- a/Documentation/user-manual.txt\n> +++ b/Documentation/user-manual.txt\n> @@ -1,4 +1,4 @@\n> -Git User's Manual (for version 1.5.1 or newer)\n> +Git User's Manual (for version 1.5.2 or newer)\n>  ______________________________________________\n\nAnother option is to leave this as is, and make a note on the\nsubproject and gitattributes section that they apply only to\n1.5.2 or later.  I am debating myself which one is better.\n\n> +[[subprojects]]\n> +Subprojects\n> +-----------\n> +\n> +Some large development efforts, such as embedded Linux distributions,\n> +are composed of a set of large projects, each with its own development\n> +team, but all of which are combined to produce the project as a whole.\n> +For example, there might be a firmware project, a hypervisor project,\n> +a kernel project, and a userspace project.  Note that while each\n> +project is conceptually independent, there are many cases in which a\n> +change to the hypervisor necessitates a change to the kernel, for\n> +example.\n>\n> +In this case it is nice to be able to reason about the state of the\n> +entire project, but also not inconvenience each development team with\n> +checking out a gigantic repository that represents the entire project.\n\nThe above makes it sound as if the primary use case is to\nartificially split a project that is otherwise a coherent whole,\nonly because split makes each piece smaller and more manageable\nto handle.  While that use case is also in scope, I do not think\nthat is the primary one.  The above description sends a wrong\nmessage, IMHO.\n\nThe intent of the current design of the subproject support is\nmore to keep track of 'subprojects' that are _not_ under your\ncontrol.  For example, an embeddd Linux appliance developer does\nnot control the kernel project, nor glibc, nor busybox.  He just\nintegrates the work by these other projects, which do not\nparticularly care during their own development about how _he_ is\nfitting things together.\n\nThe developer however is in total control of how to fit these\npieces together, along with his own userspace, to build his\nproduct.  He uses the subproject feature to bind these external\nprojects into his own project, and freeze the HEAD version for\nthese subprojects to match the appliance's own needs (\"we will\nuse this version of kernel together with that version of the\nout-of-tree driver\").  The \"embedded distribution\" example you\ngave matches this use case better.\n"},{"id":"41984","messageId":"20070512231802.GB20785@fieldses.org","threadId":"8093","inReplyTo":"20070512005844.GA24184@us.ibm.com","subject":"Re: [PATCH] Document subproject feature","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-05-12T23:18:02Z","receivedAt":"2007-05-12T23:18:02Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Fri, May 11, 2007 at 08:58:44PM -0400, Amos Waterland wrote:\n> Add a section to the user manual about the new subproject support.\n> Show how to make a subproject.\n\nLooks like a great idea.  It'll be nice to fill this out with some\ndetails--http://marc.info/?l=git&m=117885769320212&w=2 might provide\nsome starting points.\n\n--b.\n"}]}