Documentation: describe 'submodule update --remote' use case

Make it clear that there is no implicit floating going on; --remote
lets you explicitly integrate the upstream branch in your current
HEAD (just like running 'git pull' in the submodule).  The only
distinction with the current 'git pull' is the config location and
setting used for the upstream branch, which is hopefully clear now.

Signed-off-by: W. Trevor King <wking@tremily.us>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 2e1c7a28d0fb00714748bf21de02c1f044a39b62..21cb59a6d6d9dd87754e2b20ec47bc67147370c7 100644 (file)
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -299,6 +299,16 @@ In order to ensure a current tracking branch state, `update --remote`
 fetches the submodule's remote repository before calculating the
 SHA-1.  If you don't want to fetch, you should use `submodule update
 --remote --no-fetch`.
++
+Use this option to integrate changes from the upstream subproject with
+your submodule's current HEAD.  Alternatively, you can run `git pull`
+from the submodule, which is equivalent except for the remote branch
+name: `update --remote` uses the default upstream repository and
+`submodule.<name>.branch`, while `git pull` uses the submodule's
+`branch.<name>.merge`.  Prefer `submodule.<name>.branch` if you want
+to distribute the default upstream branch with the superproject and
+`branch.<name>.merge` if you want a more native feel while working in
+the submodule itself.
 
 -N::
 --no-fetch::