Documentation: update the introductory section

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index b72964947afcc39af3b97c5b9eeb1969b44e0d05..9e488c0aad433f7478d1334e53f8c5e5dd1878ed 100644 (file)
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -43,9 +43,9 @@ 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.
+A record in the `.gitmodules` (see linkgit:gitmodules[5]) 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').
 
@@ -140,7 +140,8 @@ update::
        checkout the commit specified in the index of the containing repository.
        This will make the submodules HEAD be detached unless `--rebase` or
        `--merge` is specified or the key `submodule.$name.update` is set to
-       `rebase`, `merge` or `none`.
+       `rebase`, `merge` or `none`. `none` can be overriden by specifying
+       `--checkout`.
 +
 If the submodule is not yet initialized, and you just want to use the
 setting as stored in .gitmodules, you can automatically initialize the
@@ -148,10 +149,6 @@ submodule with the `--init` option.
 +
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
-+
-If the configuration key `submodule.$name.update` is set to `none` the
-submodule with name `$name` will not be updated by default. This can be
-overriden by adding `--checkout` to the command.
 
 summary::
        Show commit summary between the given commit (defaults to HEAD) and
@@ -190,7 +187,7 @@ commit for each submodule.
 sync::
        Synchronizes submodules' remote URL configuration setting
        to the value specified in .gitmodules. It will only affect those
-       submodules which already have an url entry in .git/config (that is the
+       submodules which already have a URL entry in .git/config (that is the
        case when they are initialized or freshly added). This is useful when
        submodule URLs change upstream and you need to update your local
        repositories accordingly.