From: W. Trevor King <wking@tremily.us>
Date: Fri, 9 Nov 2012 02:52:11 +0000 (-0500)
Subject: git-submodule: Motivate --record with an example use case
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=refs%2Fheads%2Fwtk%2Fsubmodule.name.branch-v2;p=git.git

git-submodule: Motivate --record with an example use case

Signed-off-by: W. Trevor King <wking@tremily.us>
---

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 9a99826d5..d4e993faf 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -220,6 +220,14 @@ OPTIONS
 	is not set either, `HEAD` will be recorded.  Because the branch name
 	is optional, you must use the equal-sign form (`-r=<branch>`), not
 	`-r <branch>`.
++
+The recorded setting is not actually used by git; however, some
+external tools and workflows may make use of it.  For example, if the
+upstream branches still exist and you have a recorded branch setting
+for each of your submodules, you can update all of the submodules to
+the current branch tips with:
++
+	git submodule foreach 'git checkout $submodule_branch && git pull'
 
 -f::
 --force::