Merge branch 'sb/submodule-doc-intro'

* sb/submodule-doc-intro:
  submodule doc: reorder introductory paragraphs

Documentation/git-submodule.txt

@@ -25,22 +25,17 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Submodules allow foreign repositories to be embedded within
+Inspects, updates and manages submodules.
-a dedicated subdirectory of the source tree, always pointed
-at a particular commit.
 
-They are not to be confused with remotes, which are meant mainly
+A submodule allows you to keep another Git repository in a subdirectory
-for branches of the same project; submodules are meant for
+of your repository. The other repository has its own history, which does not
-different projects you would like to make part of your source tree,
+interfere with the history of the current repository. This can be used to
-while the history of the two projects still stays completely
+have external dependencies such as third party libraries for example.
-independent and you cannot modify the contents of the submodule
+
-from within the main project.
+When cloning or pulling a repository containing submodules however,
-If you want to merge the project histories and want to treat the
+these will not be checked out by default; the 'init' and 'update'
-aggregated whole as a single project from then on, you may want to
+subcommands will maintain submodules checked out and at
-add a remote for the other project and use the 'subtree' merge strategy,
+appropriate revision in your working tree.
-instead of treating the other project as a submodule. Directories
-that come from both projects can be cloned and checked out as a whole
-if you choose to go that route.
 
 Submodules are composed from a so-called `gitlink` tree entry
 in the main repository that refers to a particular commit object
@@ -51,19 +46,18 @@ describes the default URL the submodule shall be cloned from.
 The logical name can be used for overriding this URL within your
 local repository configuration (see 'submodule init').
 
-This command will manage the tree entries and contents of the
+Submodules are not to be confused with remotes, which are other
-gitmodules file for you, as well as inspect the status of your
+repositories of the same project; submodules are meant for
-submodules and update them.
+different projects you would like to make part of your source tree,
-When adding a new submodule to the tree, the 'add' subcommand
+while the history of the two projects still stays completely
-is to be used.  However, when pulling a tree containing submodules,
+independent and you cannot modify the contents of the submodule
-these will not be checked out by default;
+from within the main project.
-the 'init' and 'update' subcommands will maintain submodules
+If you want to merge the project histories and want to treat the
-checked out and at appropriate revision in your working tree.
+aggregated whole as a single project from then on, you may want to
-You can briefly inspect the up-to-date status of your submodules
+add a remote for the other project and use the 'subtree' merge strategy,
-using the 'status' subcommand and get a detailed overview of the
+instead of treating the other project as a submodule. Directories
-difference between the index and checkouts using the 'summary'
+that come from both projects can be cloned and checked out as a whole
-subcommand.
+if you choose to go that route.
-
 
 COMMANDS
 --------