[PATCH] Documentation/git-submodule.txt: Add Description section

[Petr Baudis <pasky@suse.cz>]

Figuring out how submodules work conceptually is quite a bumpy
ride for a newcomer; the user manual helps (if one knows to actually
look into it), but the reference documentation should provide good
quick intro as well. This patch attempts to do that.

Signed-off-by: Petr Baudis <pasky@suse.cz>
---

 Documentation/git-submodule.txt |   18 ++++++++++++++++++
 1 files changed, 18 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 105fc2d..3413704 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -16,6 +16,24 @@ SYNOPSIS
 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
 
 
+DESCRIPTION
+-----------
+Submodules are a special kind of tree entries which do not refer to a blob or
+a directory, but to a particular tree in another repository (living at a given
+URL).  The tree entry describes the existence of a submodule with the given
+name and the exact revision that should be used, while the location of the
+repository is described in the `/.gitmodules` file.  This command will manage
+the tree entries and contents of this 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.
+
+
 COMMANDS
 --------
 add::