user-manual: Explain what submodules are good for.
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. Signed-off-by: Michael Smith <msmith@cbnco.com> Acked-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Smith committed
Sep 25, 2007 at 08:44 UTC
6dd14366d9478fdb3b459e1b39e384deb5f38f9f
1 file changed
+42
-12
Documentation/user-manual.txt
+42
-12
@@ -2856,8 +2856,7 @@ between two related tree objects, since it can ignore any entries with
2856
identical object names.
2857
2858
(Note: in the presence of submodules, trees may also have commits as
2859
-entries. See gitlink:git-submodule[1] and gitlink:gitmodules.txt[1]
2860
-for partial documentation.)
2859
+entries. See <<submodules>> for documentation.)
2860
2861
Note that the files all have mode 644 or 755: git actually only pays
2862
attention to the executable bit.
@@ -3163,12 +3162,45 @@ information as long as you have the name of the tree that it described.
3162
Submodules
3163
==========
3164
3166
-This tutorial explains how to create and publish a repository with submodules
3167
-using the gitlink:git-submodule[1] command.
3168
-
3169
-Submodules maintain their own identity; the submodule support just stores the
3170
-submodule repository location and commit ID, so other developers who clone the
3171
-superproject can easily clone all the submodules at the same revision.
3165
+Large projects are often composed of smaller, self-contained modules. For
3166
+example, an embedded Linux distribution's source tree would include every
3167
+piece of software in the distribution with some local modifications; a movie
3168
+player might need to build against a specific, known-working version of a
3169
+decompression library; several independent programs might all share the same
3170
+build scripts.
3171
+
3172
+With centralized revision control systems this is often accomplished by
3173
+including every module in one single repository. Developers can check out
3174
+all modules or only the modules they need to work with. They can even modify
3175
+files across several modules in a single commit while moving things around
3176
+or updating APIs and translations.
3177
+
3178
+Git does not allow partial checkouts, so duplicating this approach in Git
3179
+would force developers to keep a local copy of modules they are not
3180
+interested in touching. Commits in an enormous checkout would be slower
3181
+than you'd expect as Git would have to scan every directory for changes.
3182
+If modules have a lot of local history, clones would take forever.
3183
+
3184
+On the plus side, distributed revision control systems can much better
3185
+integrate with external sources. In a centralized model, a single arbitrary
3186
+snapshot of the external project is exported from its own revision control
3187
+and then imported into the local revision control on a vendor branch. All
3188
+the history is hidden. With distributed revision control you can clone the
3189
+entire external history and much more easily follow development and re-merge
3190
+local changes.
3191
+
3192
+Git's submodule support allows a repository to contain, as a subdirectory, a
3193
+checkout of an external project. Submodules maintain their own identity;
3194
+the submodule support just stores the submodule repository location and
3195
+commit ID, so other developers who clone the containing project
3196
+("superproject") can easily clone all the submodules at the same revision.
3197
+Partial checkouts of the superproject are possible: you can tell Git to
3198
+clone none, some or all of the submodules.
3199
+
3200
+The gitlink:git-submodule[1] command is available since Git 1.5.3. Users
3201
+with Git 1.5.2 can look up the submodule commits in the repository and
3202
+manually check them out; earlier versions won't recognize the submodules at
3203
+all.
3204
3205
To see how submodule support works, create (for example) four example
3206
repositories that can be used later as a submodule:
@@ -3213,8 +3245,8 @@ The `git submodule add` command does a couple of things:
3245
3246
- It clones the submodule under the current directory and by default checks out
3247
the master branch.
3216
-- It adds the submodule's clone path to the `.gitmodules` file and adds this
3217
- file to the index, ready to be committed.
3248
+- It adds the submodule's clone path to the gitlink:gitmodules[5] file and
3249
+ adds this file to the index, ready to be committed.
3250
- It adds the submodule's current commit ID to the index, ready to be
3251
committed.
3252
@@ -4277,5 +4309,3 @@ Write a chapter on using plumbing and writing scripts.
4309
Alternates, clone -reference, etc.
4310
4311
git unpack-objects -r for recovery
4280
-
4281
-submodules