Autogenerated HTML docs for v1.5.6.4-433-g09651

1 files changed, 47 insertions, 22 deletions

diff --git a/git-submodule.txt b/git-submodule.txt
index bb4e6fbf5..829b03201 100644
--- a/git-submodule.txt
+++ b/git-submodule.txt
@@ -18,24 +18,44 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Submodules are a special kind of tree entries which refer to a particular tree
-state in another repository.  The tree entry describes
-the existence of a submodule with the given name and the exact revision that
-should be used, while an entry in `.gitmodules` file gives the location of
-the repository.
-
-When checked out, submodules will maintain their own independent repositories
-within their directories; the only link between the submodule and the "parent
-project" is the tree entry within the parent project mentioned above.
-
-This command will manage the tree entries and contents of the gitmodules file
-for you, as well as inspecting the status of your submodules and updating them.
-When adding a new submodule to the tree, the 'add' subcommand is to be used.
-However, when pulling a tree containing submodules, these will not be checked
-out by default; the 'init' and 'update' subcommands will maintain submodules
-checked out and at appropriate revision in your working tree. You can inspect
-the current status of your submodules using the 'submodule' subcommand and get
-an overview of changes 'update' would perform using the 'summary' subcommand.
+Submodules allow foreign repositories to be embedded within
+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
+for branches of the same project; submodules are meant for
+different projects you would like to make part of your source tree,
+while the history of the two projects still stays completely
+independent and you cannot modify the contents of the submodule
+from within the main project.
+If you want to merge the project histories and want to treat the
+aggregated whole as a single project from then on, you may want to
+add a remote for the other project and use the 'subtree' merge strategy,
+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
+within the inner repository that is completely separate.
+A record in the `.gitmodules` file at the root of the source
+tree assigns a logical name to the submodule and 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
+gitmodules file for you, as well as inspect the status of your
+submodules and update them.
+When adding a new submodule to the tree, the 'add' subcommand
+is to be used.  However, when pulling a tree containing submodules,
+these will not be checked out by default;
+the 'init' and 'update' subcommands will maintain submodules
+checked out and at appropriate revision in your working tree.
+You can briefly inspect the up-to-date status of your submodules
+using the 'status' subcommand and get a detailed overview of the
+difference between the index and checkouts using the 'summary'
+subcommand.
 
 
 COMMANDS
@@ -78,10 +98,15 @@ status::
 	repository. This command is the default command for 'git-submodule'.
 
 init::
-	Initialize the submodules, i.e. register in .git/config each submodule
-	name and url found in .gitmodules. The key used in .git/config is
-	`submodule.$name.url`. This command does not alter existing information
-	in .git/config.
+	Initialize the submodules, i.e. register each submodule name
+	and url found in .gitmodules into .git/config.
+	The key used in .git/config is `submodule.$name.url`.
+	This command does not alter existing information in .git/config.
+	You can then customize the submodule clone URLs in .git/config
+	for your local setup and proceed to 'git submodule update';
+	you can also just use 'git submodule update --init' without
+	the explicit 'init' step if you do not intend to customize
+	any submodule locations.
 
 update::
 	Update the registered submodules, i.e. clone missing submodules and