@matheusbsbs / matheus-bagliano / commits / 6dd14366d9
Fork 0

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