[RFC] submodule: change submodule.<name>.branch default from master to HEAD

From: W. Trevor King <wking@tremily.us>
Date: Mar 28, 2014, 03:36 UTC
Message-ID: <c66d89d854407469b6fd223213a09e5d60eeec0a.1395977055.git.wking@tremily.us>
In-Reply-To: <20140328030556.GD25485@odin.tremily.us>

gitmodule(5) mentioned 'master' as the default remote branch, but folks using checkout-style updates are unlikely to care which upstream branch their commit comes from (they only care that the clone fetches that commit). If they haven't set submodule.<name>.branch, it makes more sense to mirror 'git clone' and use the subproject's HEAD than to default to 'master' (which may not even exist).

After the initial clone, subsequent updates may be local or remote. Local updates (integrating gitlink changes) have no need to fetch a specific remote branch, and get along just fine without submodule.<name>.branch. Remote updates do need a remote branch, but HEAD works as well here as it did for the initial clone.

Reported-by: Johan Herland <johan@herland.net>
Signed-off-by: W. Trevor King <wking@tremily.us>
---
This still needs tests, but it gets through the following fine:

  rm -rf superproject subproject &&
  mkdir subproject &&
  (cd subproject &&
   git init &&
   echo 'Subproject' > README &&
   git add README &&
   git commit -m 'Subproject commit' &&
   git branch -m master next
  ) &&
  mkdir superproject &&
  (cd superproject &&
   git init &&
   git submodule add ../subproject submod &&
   git commit -am 'Add submod'
  )
  (cd subproject &&
   echo 'work work work' >> README &&
   git commit -am 'Subproject commit 2'
  ) &&
  (cd superproject &&
   git submodule update --remote &&
   git commit -am 'Add submod'
  )

The main drawback to this approach is that we're changing a default, but I agree with John's:

On Fri, Mar 28, 2014 at 12:21:23AM +0100, Johan Herland wrote:

> I expect in most cases where "origin/master" happens to be the Right
> Answer, using the submodule's upstream's HEAD will yield the same
> result.

so the default-change may not be particularly intrusive.

Cheers, Trevor

 Documentation/git-submodule.txt |  2 +-
 Documentation/gitmodules.txt    |  5 +++--
 git-submodule.sh                | 11 ++++++++---
 3 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 46c1eeb..c485a17 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -284,7 +284,7 @@ OPTIONS
 	the superproject's recorded SHA-1 to update the submodule, use the
 	status of the submodule's remote-tracking branch.  The remote used
 	is branch's remote (`branch.<name>.remote`), defaulting to `origin`.
-	The remote branch used defaults to `master`, but the branch name may
+	The remote branch used defaults to `HEAD`, but the branch name may
 	be overridden by setting the `submodule.<name>.branch` option in
 	either `.gitmodules` or `.git/config` (with `.git/config` taking
 	precedence).
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index f539e3f..1aecce9 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -53,8 +53,9 @@ submodule.<name>.update::
 
 submodule.<name>.branch::
 	A remote branch name for tracking updates in the upstream submodule.
-	If the option is not specified, it defaults to 'master'.  See the
-	`--remote` documentation in linkgit:git-submodule[1] for details.
+	If the option is not specified, it defaults to the subproject's
+	HEAD.  See the `--remote` documentation in linkgit:git-submodule[1]
+	for details.
 +
 This branch name is also used for the local branch created by
 non-checkout cloning updates.  See the `update` documentation in
diff --git a/git-submodule.sh b/git-submodule.sh
index 6135cfa..5f08e6c 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -819,8 +819,8 @@ cmd_update()
 		name=$(module_name "$sm_path") || exit
 		url=$(git config submodule."$name".url)
 		config_branch=$(get_submodule_config "$name" branch)
-		branch="${config_branch:-master}"
-		local_branch="$branch"
+		branch="${config_branch:-HEAD}"
+		local_branch="$config_branch"
 		if ! test -z "$update"
 		then
 			update_module=$update
@@ -860,7 +860,12 @@ Maybe you want to use 'update --init'?")"
 
 		if ! test -d "$sm_path"/.git -o -f "$sm_path"/.git
 		then
-			start_point="origin/${branch}"
+			if test -n "$config_branch"
+			then
+				start_point="origin/$branch"
+			else
+				start_point=""
+			fi
 			module_clone "$sm_path" "$name" "$url" "$reference" "$depth" "$start_point" "$local_branch" || exit
 			cloned_modules="$cloned_modules;$name"
 			subsha1=

-- 
1.9.1.352.gd393d14.dirty