{"thread":{"id":"9991","subject":"[PATCH] user-manual: Explain what submodules are good for.","startedAt":"2007-09-24T03:14:09Z","lastAt":"2007-09-25T16:09:05Z","messageCount":5,"participants":["Michael Smith","J. Bruce Fields"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"53886","messageId":"11906036491118-git-send-email-msmith@cbnco.com","threadId":"9991","inReplyTo":null,"subject":"[PATCH] user-manual: Explain what submodules are good for.","fromName":"Michael Smith","fromEmail":"msmith@cbnco.com","sentAt":"2007-09-24T03:14:09Z","receivedAt":"2007-09-24T03:14:09Z","isPatch":true,"sender":{"key":"msmith@cbnco.com","avatar":null},"body":"Rework the introduction to the Submodules section to explain why\nsomeone would use them, and fix up submodule references from the\ntree-object and todo sections.\n\nSigned-off-by: Michael Smith <msmith@cbnco.com>\n---\n Documentation/user-manual.txt |   25 ++++++++++++++-----------\n 1 files changed, 14 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex a085ca1..bd77e62 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -2856,8 +2856,7 @@ between two related tree objects, since it can ignore any entries with\n identical object names.\n \n (Note: in the presence of submodules, trees may also have commits as\n-entries.   See gitlink:git-submodule[1] and gitlink:gitmodules.txt[1]\n-for partial documentation.)\n+entries.  See <<submodules>> for documentation.)\n \n Note that the files all have mode 644 or 755: git actually only pays\n attention to the executable bit.\n@@ -3163,12 +3162,18 @@ information as long as you have the name of the tree that it described.\n Submodules\n ==========\n \n-This tutorial explains how to create and publish a repository with submodules\n-using the gitlink:git-submodule[1] command.\n+Some large projects are composed of smaller, self-contained parts.  For\n+example, an embedded Linux distribution's source tree would include every\n+piece of software in the distribution; a movie player might need to build\n+against a specific, known-working version of a decompression library;\n+several independent programs might all share the same build scripts.\n \n-Submodules maintain their own identity; the submodule support just stores the\n-submodule repository location and commit ID, so other developers who clone the\n-superproject can easily clone all the submodules at the same revision.\n+Git's submodule support allows a repository to contain, as a subdirectory, a\n+checkout of an external project.  Submodules maintain their own identity;\n+the submodule support just stores the submodule repository location and\n+commit ID, so other developers who clone the superproject can easily clone\n+all the submodules at the same revision.  The gitlink:git-submodule[1]\n+command manages submodules.\n \n To see how submodule support works, create (for example) four example\n repositories that can be used later as a submodule:\n@@ -3213,8 +3218,8 @@ The `git submodule add` command does a couple of things:\n \n - It clones the submodule under the current directory and by default checks out\n   the master branch.\n-- It adds the submodule's clone path to the `.gitmodules` file and adds this\n-  file to the index, ready to be committed.\n+- It adds the submodule's clone path to the gitlink:gitmodules[5] file and\n+  adds this file to the index, ready to be committed.\n - It adds the submodule's current commit ID to the index, ready to be\n   committed.\n \n@@ -4277,5 +4282,3 @@ Write a chapter on using plumbing and writing scripts.\n Alternates, clone -reference, etc.\n \n git unpack-objects -r for recovery\n-\n-submodules\n-- \n1.5.3\n"},{"id":"53947","messageId":"20070924213342.GL26387@fieldses.org","threadId":"9991","inReplyTo":"11906036491118-git-send-email-msmith@cbnco.com","subject":"Re: [PATCH] user-manual: Explain what submodules are good for.","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-09-24T21:33:42Z","receivedAt":"2007-09-24T21:33:42Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sun, Sep 23, 2007 at 11:14:09PM -0400, Michael Smith wrote:\n> Rework the introduction to the Submodules section to explain why\n> someone would use them, and fix up submodule references from the\n> tree-object and todo sections.\n\nThanks!\n\n> +Some large projects are composed of smaller, self-contained parts.  For\n> +example, an embedded Linux distribution's source tree would include every\n> +piece of software in the distribution; a movie player might need to build\n> +against a specific, known-working version of a decompression library;\n> +several independent programs might all share the same build scripts.\n...\n> +Git's submodule support allows a repository to contain, as a subdirectory, a\n> +checkout of an external project.  Submodules maintain their own identity;\n> +the submodule support just stores the submodule repository location and\n> +commit ID, so other developers who clone the superproject can easily clone\n> +all the submodules at the same revision.  The gitlink:git-submodule[1]\n> +command manages submodules.\n\nThat looks helpful, thanks, but a little more detail might be nice.\n\nImagining myself as a reader trying to decide whether to use submodules\nin a given case, I'm not sure this would tell me everything I need to\nknow.  For example, how does this compare to just importing a snapshot\nof the library into your tree?  (Or possibly using the subtree merge\nstrategy?)\n\nSome issues that pop to mind are scalability (when does a monolithic\ntree get too large to work with?) and backwards compatibility (what\nversion does everybody working on your project need to have for it to\nwork?  What problems will you see if a few people are stuck with an\nolder git?)  I haven't followed submodule development, though, so may\nhave missed more important issues.\n\n--b.\n"},{"id":"53986","messageId":"Pine.LNX.4.64.0709250841410.6203@juice.ott.cti.com","threadId":"9991","inReplyTo":"20070924213342.GL26387@fieldses.org","subject":"Re: [PATCH] user-manual: Explain what submodules are good for.","fromName":"Michael Smith","fromEmail":"msmith@cbnco.com","sentAt":"2007-09-25T12:44:06Z","receivedAt":"2007-09-25T12:44:06Z","isPatch":true,"sender":{"key":"msmith@cbnco.com","avatar":null},"body":"On Mon, 24 Sep 2007, J. Bruce Fields wrote:\n\n> That looks helpful, thanks, but a little more detail might be nice.\n\nOK, let's find out if I'm awake enough to git-send-email.\n\nMike\n"},{"id":"53987","messageId":"1190724278-8586-1-git-send-email-msmith@cbnco.com","threadId":"9991","inReplyTo":"Pine.LNX.4.64.0709250841410.6203@juice.ott.cti.com","subject":"[PATCH] user-manual: Explain what submodules are good for.","fromName":"Michael Smith","fromEmail":"msmith@cbnco.com","sentAt":"2007-09-25T12:44:38Z","receivedAt":"2007-09-25T12:44:38Z","isPatch":true,"sender":{"key":"msmith@cbnco.com","avatar":null},"body":"Rework the introduction to the Submodules section to explain why\nsomeone would use them, and fix up submodule references from the\ntree-object and todo sections.\n\nSigned-off-by: Michael Smith <msmith@cbnco.com>\n---\n Documentation/user-manual.txt |   54 +++++++++++++++++++++++++++++++---------\n 1 files changed, 42 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex a085ca1..c7fdf25 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -2856,8 +2856,7 @@ between two related tree objects, since it can ignore any entries with\n identical object names.\n \n (Note: in the presence of submodules, trees may also have commits as\n-entries.   See gitlink:git-submodule[1] and gitlink:gitmodules.txt[1]\n-for partial documentation.)\n+entries.  See <<submodules>> for documentation.)\n \n Note that the files all have mode 644 or 755: git actually only pays\n attention to the executable bit.\n@@ -3163,12 +3162,45 @@ information as long as you have the name of the tree that it described.\n Submodules\n ==========\n \n-This tutorial explains how to create and publish a repository with submodules\n-using the gitlink:git-submodule[1] command.\n-\n-Submodules maintain their own identity; the submodule support just stores the\n-submodule repository location and commit ID, so other developers who clone the\n-superproject can easily clone all the submodules at the same revision.\n+Large projects are often composed of smaller, self-contained modules.  For\n+example, an embedded Linux distribution's source tree would include every\n+piece of software in the distribution with some local modifications; a movie\n+player might need to build against a specific, known-working version of a\n+decompression library; several independent programs might all share the same\n+build scripts.\n+\n+With centralized revision control systems this is often accomplished by\n+including every module in one single repository.  Developers can check out\n+all modules or only the modules they need to work with.  They can even modify\n+files across several modules in a single commit while moving things around\n+or updating APIs and translations.\n+\n+Git does not allow partial checkouts, so duplicating this approach in Git\n+would force developers to keep a local copy of modules they are not\n+interested in touching.  Commits in an enormous checkout would be slower\n+than you'd expect as Git would have to scan every directory for changes.\n+If modules have a lot of local history, clones would take forever.\n+\n+On the plus side, distributed revision control systems can much better\n+integrate with external sources.  In a centralized model, a single arbitrary\n+snapshot of the external project is exported from its own revision control\n+and then imported into the local revision control on a vendor branch.  All\n+the history is hidden.  With distributed revision control you can clone the\n+entire external history and much more easily follow development and re-merge\n+local changes.\n+\n+Git's submodule support allows a repository to contain, as a subdirectory, a\n+checkout of an external project.  Submodules maintain their own identity;\n+the submodule support just stores the submodule repository location and\n+commit ID, so other developers who clone the containing project\n+(\"superproject\") can easily clone all the submodules at the same revision.\n+Partial checkouts of the superproject are possible: you can tell Git to\n+clone none, some or all of the submodules.\n+\n+The gitlink:git-submodule[1] command is available since Git 1.5.3.  Users\n+with Git 1.5.2 can look up the submodule commits in the repository and\n+manually check them out; earlier versions won't recognize the submodules at\n+all.\n \n To see how submodule support works, create (for example) four example\n repositories that can be used later as a submodule:\n@@ -3213,8 +3245,8 @@ The `git submodule add` command does a couple of things:\n \n - It clones the submodule under the current directory and by default checks out\n   the master branch.\n-- It adds the submodule's clone path to the `.gitmodules` file and adds this\n-  file to the index, ready to be committed.\n+- It adds the submodule's clone path to the gitlink:gitmodules[5] file and\n+  adds this file to the index, ready to be committed.\n - It adds the submodule's current commit ID to the index, ready to be\n   committed.\n \n@@ -4277,5 +4309,3 @@ Write a chapter on using plumbing and writing scripts.\n Alternates, clone -reference, etc.\n \n git unpack-objects -r for recovery\n-\n-submodules\n-- \n1.5.3\n"},{"id":"54014","messageId":"20070925160905.GF30845@fieldses.org","threadId":"9991","inReplyTo":"1190724278-8586-1-git-send-email-msmith@cbnco.com","subject":"Re: [PATCH] user-manual: Explain what submodules are good for.","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-09-25T16:09:05Z","receivedAt":"2007-09-25T16:09:05Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Tue, Sep 25, 2007 at 08:44:38AM -0400, Michael Smith wrote:\n> Rework the introduction to the Submodules section to explain why\n> someone would use them, and fix up submodule references from the\n> tree-object and todo sections.\n\nLooks good to me; thanks!\n\nAcked-by: J. Bruce Fields <bfields@citi.umich.edu>\n\n--b.\n\n> Signed-off-by: Michael Smith <msmith@cbnco.com>\n> ---\n>  Documentation/user-manual.txt |   54 +++++++++++++++++++++++++++++++---------\n>  1 files changed, 42 insertions(+), 12 deletions(-)\n> \n> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> index a085ca1..c7fdf25 100644\n> --- a/Documentation/user-manual.txt\n> +++ b/Documentation/user-manual.txt\n> @@ -2856,8 +2856,7 @@ between two related tree objects, since it can ignore any entries with\n>  identical object names.\n>  \n>  (Note: in the presence of submodules, trees may also have commits as\n> -entries.   See gitlink:git-submodule[1] and gitlink:gitmodules.txt[1]\n> -for partial documentation.)\n> +entries.  See <<submodules>> for documentation.)\n>  \n>  Note that the files all have mode 644 or 755: git actually only pays\n>  attention to the executable bit.\n> @@ -3163,12 +3162,45 @@ information as long as you have the name of the tree that it described.\n>  Submodules\n>  ==========\n>  \n> -This tutorial explains how to create and publish a repository with submodules\n> -using the gitlink:git-submodule[1] command.\n> -\n> -Submodules maintain their own identity; the submodule support just stores the\n> -submodule repository location and commit ID, so other developers who clone the\n> -superproject can easily clone all the submodules at the same revision.\n> +Large projects are often composed of smaller, self-contained modules.  For\n> +example, an embedded Linux distribution's source tree would include every\n> +piece of software in the distribution with some local modifications; a movie\n> +player might need to build against a specific, known-working version of a\n> +decompression library; several independent programs might all share the same\n> +build scripts.\n> +\n> +With centralized revision control systems this is often accomplished by\n> +including every module in one single repository.  Developers can check out\n> +all modules or only the modules they need to work with.  They can even modify\n> +files across several modules in a single commit while moving things around\n> +or updating APIs and translations.\n> +\n> +Git does not allow partial checkouts, so duplicating this approach in Git\n> +would force developers to keep a local copy of modules they are not\n> +interested in touching.  Commits in an enormous checkout would be slower\n> +than you'd expect as Git would have to scan every directory for changes.\n> +If modules have a lot of local history, clones would take forever.\n> +\n> +On the plus side, distributed revision control systems can much better\n> +integrate with external sources.  In a centralized model, a single arbitrary\n> +snapshot of the external project is exported from its own revision control\n> +and then imported into the local revision control on a vendor branch.  All\n> +the history is hidden.  With distributed revision control you can clone the\n> +entire external history and much more easily follow development and re-merge\n> +local changes.\n> +\n> +Git's submodule support allows a repository to contain, as a subdirectory, a\n> +checkout of an external project.  Submodules maintain their own identity;\n> +the submodule support just stores the submodule repository location and\n> +commit ID, so other developers who clone the containing project\n> +(\"superproject\") can easily clone all the submodules at the same revision.\n> +Partial checkouts of the superproject are possible: you can tell Git to\n> +clone none, some or all of the submodules.\n> +\n> +The gitlink:git-submodule[1] command is available since Git 1.5.3.  Users\n> +with Git 1.5.2 can look up the submodule commits in the repository and\n> +manually check them out; earlier versions won't recognize the submodules at\n> +all.\n>  \n>  To see how submodule support works, create (for example) four example\n>  repositories that can be used later as a submodule:\n> @@ -3213,8 +3245,8 @@ The `git submodule add` command does a couple of things:\n>  \n>  - It clones the submodule under the current directory and by default checks out\n>    the master branch.\n> -- It adds the submodule's clone path to the `.gitmodules` file and adds this\n> -  file to the index, ready to be committed.\n> +- It adds the submodule's clone path to the gitlink:gitmodules[5] file and\n> +  adds this file to the index, ready to be committed.\n>  - It adds the submodule's current commit ID to the index, ready to be\n>    committed.\n>  \n> @@ -4277,5 +4309,3 @@ Write a chapter on using plumbing and writing scripts.\n>  Alternates, clone -reference, etc.\n>  \n>  git unpack-objects -r for recovery\n> -\n> -submodules\n> -- \n> 1.5.3\n> \n"}]}