Subject: Re: [PATCH v2] git-submodule add: Add -r/--record option.

From: Jens Lehmann <[email-masked]>
Date: Wed, 24 Oct 2012 21:15:32 +0200

I still fail to see what adding that functionality to the submodule
command buys us (unless we also add code which really uses the branch
setting). What's wrong with doing a simple:

   git config -f .gitmodules submodule.<path>.branch <record_branch>

on the command line when you want to use the branch setting for your
own purposes? You could easily wrap that into a helper script, no?

Am 23.10.2012 23:57, schrieb W. Trevor King:
> From: "W. Trevor King" <[email-masked]>
> 
> This option allows you to record a submodule.<name>.branch option in
> .gitmodules.  Git does not currently use this configuration option for
> anything, but users have used it for several things, so it makes sense
> to add some syntactic sugar for initializing the value.
> 
> Current consumers:
> 
> Ævar uses this setting to designate the upstream branch for pulling
> submodule updates:
> 
>   $ git submodule foreach 'git checkout $(git config --file $toplevel/.gitmodules submodule.$name.branch) && git pull'
> 
> as he describes in
> 
>   commit f030c96d8643fa0a1a9b2bd9c2f36a77721fb61f
>   Author: Ævar Arnfjörð Bjarmason <[email-masked]>
>   Date:   Fri May 21 16:10:10 2010 +0000
> 
>     git-submodule foreach: Add $toplevel variable
> 
> Gerrit uses this setting to
> 
>   “indicate the branch of a submodule project that when updated will
>   trigger automatic update of its registered gitlink.” [1]
> 
> I'm not clear on what that means, but they accept special values like
> '.', so their usage is not compatible with Ævar's proposal.
> 
> By remaining agnostic on the variable usage, this patch makes
> submodule setup more convenient for all parties.
> 
> [1] https://gerrit.googlesource.com/gerrit/+/master/Documentation/user-submodules.txt
> 
> Signed-off-by: W. Trevor King <[email-masked]>
> ---
>  Documentation/git-submodule.txt | 11 ++++++++++-
>  git-submodule.sh                | 19 ++++++++++++++++++-
>  t/t7400-submodule-basic.sh      | 25 +++++++++++++++++++++++++
>  3 files changed, 53 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index b4683bb..f9c74d6 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -9,7 +9,7 @@ git-submodule - Initialize, update or inspect submodules
>  SYNOPSIS
>  --------
>  [verse]
> -'git submodule' [--quiet] add [-b branch] [-f|--force]
> +'git submodule' [--quiet] add [-b branch] [--record[=<branch>]] [-f|--force]
>  	      [--reference <repository>] [--] <repository> [<path>]
>  'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
>  'git submodule' [--quiet] init [--] [<path>...]
> @@ -209,6 +209,15 @@ OPTIONS
>  --branch::
>  	Branch of repository to add as submodule.
>  
> +-r::
> +--record::
> +  Record a branch name used as `submodule.<path>.branch` in
> +  `.gitmodules` for future reference.  If you do not list an explicit
> +  name here, the name given with `--branch` will be recorded.  If that
> +  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>`.
> +
>  -f::
>  --force::
>  	This option is only valid for add and update commands.
> diff --git a/git-submodule.sh b/git-submodule.sh
> index ab6b110..bc33112 100755
> --- a/git-submodule.sh
> +++ b/git-submodule.sh
> @@ -5,7 +5,7 @@
>  # Copyright (c) 2007 Lars Hjemli
>  
>  dashless=$(basename "$0" | sed -e 's/-/ /')
> -USAGE="[--quiet] add [-b branch] [-f|--force] [--reference <repository>] [--] <repository> [<path>]
> +USAGE="[--quiet] add [-b branch] [--record[=<branch>]] [-f|--force] [--reference <repository>] [--] <repository> [<path>]
>     or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...]
>     or: $dashless [--quiet] init [--] [<path>...]
>     or: $dashless [--quiet] update [--init] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...]
> @@ -20,6 +20,8 @@ require_work_tree
>  
>  command=
>  branch=
> +record_branch=
> +record_branch_empty=
>  force=
>  reference=
>  cached=
> @@ -257,6 +259,12 @@ cmd_add()
>  			branch=$2
>  			shift
>  			;;
> +		-r | --record)
> +			record_branch_empty=true
> +			;;
> +		-r=* | --record=*)
> +			record_branch="${1#*=}"
> +			;;
>  		-f | --force)
>  			force=$1
>  			;;
> @@ -328,6 +336,11 @@ cmd_add()
>  	git ls-files --error-unmatch "$sm_path" > /dev/null 2>&1 &&
>  	die "$(eval_gettext "'\$sm_path' already exists in the index")"
>  
> +	if test -z "$record_branch" && test "$record_branch_empty" = "true"
> +	then
> +		record_branch="${branch:=HEAD}"
> +	fi
> +
>  	if test -z "$force" && ! git add --dry-run --ignore-missing "$sm_path" > /dev/null 2>&1
>  	then
>  		eval_gettextln "The following path is ignored by one of your .gitignore files:
> @@ -366,6 +379,10 @@ Use -f if you really want to add it." >&2
>  
>  	git config -f .gitmodules submodule."$sm_path".path "$sm_path" &&
>  	git config -f .gitmodules submodule."$sm_path".url "$repo" &&
> +	if test -n "$branch"
> +	then
> +		git config -f .gitmodules submodule."$sm_path".branch "$record_branch"
> +	fi &&
>  	git add --force .gitmodules ||
>  	die "$(eval_gettext "Failed to register submodule '\$sm_path'")"
>  }
> diff --git a/t/t7400-submodule-basic.sh b/t/t7400-submodule-basic.sh
> index 5397037..88ae74c 100755
> --- a/t/t7400-submodule-basic.sh
> +++ b/t/t7400-submodule-basic.sh
> @@ -133,6 +133,7 @@ test_expect_success 'submodule add --branch' '
>  	(
>  		cd addtest &&
>  		git submodule add -b initial "$submodurl" submod-branch &&
> +		test -z "$(git config -f .gitmodules submodule.submod-branch.branch)" &&
>  		git submodule init
>  	) &&
>  
> @@ -211,6 +212,30 @@ test_expect_success 'submodule add with ./, /.. and // in path' '
>  	test_cmp empty untracked
>  '
>  
> +test_expect_success 'submodule add --record' '
> +	(
> +		cd addtest &&
> +		git submodule add -r "$submodurl" submod-record-head &&
> +		test "$(git config -f .gitmodules submodule.submod-record-head.branch)" = "HEAD"
> +	)
> +'
> +
> +test_expect_success 'submodule add --record --branch' '
> +	(
> +		cd addtest &&
> +		git submodule add -r -b initial "$submodurl" submod-auto-record &&
> +		test "$(git config -f .gitmodules submodule.submod-auto-record.branch)" = "initial"
> +	)
> +'
> +
> +test_expect_success 'submodule add --record=<name> --branch' '
> +	(
> +		cd addtest &&
> +		git submodule add -r=final -b initial "$submodurl" submod-record &&
> +		test "$(git config -f .gitmodules submodule.submod-record.branch)" = "final"
> +	)
> +'
> +
>  test_expect_success 'setup - add an example entry to .gitmodules' '
>  	GIT_CONFIG=.gitmodules \
>  	git config submodule.example.url git://example.com/init.git
>