Merge branch 'wk/submodule-on-branch'

Make sure 'submodule update' modes that do not detach HEADs can
be used more pleasantly by checking out a concrete branch when
cloning them to prime the well.

* wk/submodule-on-branch:
  Documentation: describe 'submodule update --remote' use case
  submodule: explicit local branch creation in module_clone
  submodule: document module_clone arguments in comments
  submodule: make 'checkout' update_module mode more explicit

1 files changed, 37 insertions, 1 deletions

diff --git a/t/t7406-submodule-update.sh b/t/t7406-submodule-update.sh
index 0246e80b1..28ca76384 100755
--- a/t/t7406-submodule-update.sh
+++ b/t/t7406-submodule-update.sh
@@ -63,6 +63,9 @@ test_expect_success 'setup a submodule tree' '
 	 git submodule add ../none none &&
 	 test_tick &&
 	 git commit -m "none"
+	) &&
+	(cd super &&
+	 git tag initial-setup
 	)
 '
 
@@ -703,7 +706,7 @@ test_expect_success 'submodule update places git-dir in superprojects git-dir re
 	git clone super_update_r super_update_r2 &&
 	(cd super_update_r2 &&
 	 git submodule update --init --recursive >actual &&
-	 test_i18ngrep "Submodule path .submodule/subsubmodule.: checked out" actual &&
+	 test_i18ngrep "Submodule path .submodule/subsubmodule.: .git reset --hard -q" actual &&
 	 (cd submodule/subsubmodule &&
 	  git log > ../../expected
 	 ) &&
@@ -775,4 +778,37 @@ test_expect_success 'submodule update --recursive drops module name before recur
 	)
 '
 
+test_expect_success 'submodule update --checkout clones detached HEAD' '
+	git clone super super4 &&
+	echo "detached HEAD" >expected &&
+	(cd super4 &&
+	 git reset --hard initial-setup &&
+	 git submodule init submodule &&
+	 git submodule update >> /tmp/log 2>&1 &&
+	 (cd submodule &&
+	  git symbolic-ref HEAD > ../../actual ||
+	  echo "detached HEAD" > ../../actual
+	 )
+	) &&
+	test_cmp actual expected &&
+	rm -rf super4
+'
+
+test_expect_success 'submodule update --merge clones attached HEAD' '
+	git clone super super4 &&
+	echo "refs/heads/master" >expected &&
+	(cd super4 &&
+	 git reset --hard initial-setup &&
+	 git submodule init submodule &&
+	 git config submodule.submodule.update merge &&
+	 git submodule update --merge &&
+	 (cd submodule &&
+	  git symbolic-ref HEAD > ../../actual ||
+	  echo "detached HEAD" > ../../actual
+	 )
+	) &&
+	test_cmp actual expected &&
+	rm -rf super4
+'
+
 test_done