version: add git_user_agent function

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 3b05498c1035b15ae4db134880a111b777106b0d..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').
 
@@ -79,7 +79,14 @@ to exist in the superproject. If <path> is not given, the
 <repository> is the URL of the new submodule's origin repository.
 This may be either an absolute URL, or (if it begins with ./
 or ../), the location relative to the superproject's origin
-repository.
+repository (Please note that to specify a repository 'foo.git'
+which is located right next to a superproject 'bar.git', you'll
+have to use '../foo.git' instead of './foo.git' - as one might expect
+when following the rules for relative URLs - because the evaluation
+of relative URLs in Git is identical to that of relative directories).
+If the superproject doesn't have an origin configured
+the superproject is its own authoritative upstream and the current
+working directory is used instead.
 +
 <path> is the relative location for the cloned submodule to
 exist in the superproject. If <path> does not exist, then the
@@ -118,6 +125,8 @@ too (and can also report changes to a submodule's work tree).
 init::
        Initialize the submodules, i.e. register each submodule name
        and url found in .gitmodules into .git/config.
+       It will also copy the value of `submodule.$name.update` 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
@@ -131,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` or `merge`.
+       `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
@@ -176,12 +186,14 @@ commit for each submodule.
 
 sync::
        Synchronizes submodules' remote URL configuration setting
-       to the value specified in .gitmodules.  This is useful when
+       to the value specified in .gitmodules. It will only affect those
+       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.
 +
 "git submodule sync" synchronizes all submodules while
-"git submodule sync -- A" synchronizes submodule "A" only.
+"git submodule sync \-- A" synchronizes submodule "A" only.
 
 OPTIONS
 -------