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

> 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=
>