[PATCH/RFC] Introduce git submodule add|update --attach

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hello everybody,

by default "git submodule" performs its add or update operations on a detached
HEAD. This works well when using an existing full-fledged/indipendent project as
the submodule, as there's less frequent need to update it or commit back
changes. When the submodule is actually a large portion of shareable code
between  different projects, and the superproject needs to track very closely
the evolution of the submodule (or the other way around), I feel more confortable
to reattach the HEAD of the submodule with an existing branch. This can be as
simple as having a superproject "project1" in branch "master" with a submodule
"common" attached to the branch "master-project1" or, in a more development
workflow, "project1" in branch "featureA" with the same submodule "common"
attached to a similarly named branch "featureA". Doing this in git requires me
the following:

# Maintainer
$ git submodule add --branch "master-project1" <repository> common
$ git commit -m "Added submodule"
$ git config -f .gitmodules submodule.common.ignore all
$ git push
$ cd <path>
$ git checkout "master-project1"

# Developer
$ git pull
$ git submodule init
$ git submodule update --remote
$ cd <path>
$ branch="$(git config -f ..\.gitmodules submodule.common.branch)"; git checkout $branch

While the burden for the repository maitainer/administrator is acceptable, in
the developer point of view there are two problems:
1) Checking out an attached HEAD of a specified branch as when using "--remote"
is not really simple as it could be and could require lauching of scrips or
reading some repository specific documentation. Also in Windows platform the
syntax for inline shell evaluation of commands is less known between users;
2) There's no way to store a similar default behaviour in the repository except
by using scripts. Also recently submodule.<modulename>.update custom !commands
in no more supported when stored in .gitmodules [1].

The attached patch tries to solve these problems by introducing an "--attach"
switch to the "add" and "update" submodule commands and a "--detach" switch just
for the "update" command. It also add the support for an 'submodule.<name>.attach'
property when updating. Using the "--attach" switch when adding a submodule does:
- create the submodule checking out an attached HEAD;
- set the 'submodule.<name>.attach' property to 'true';
- set the 'submodule.<name>.ignore' property to 'all' (this is useful as
attaching to the branch doesn't require tracking of revision sha1).

The rationale of setting 'attach' and 'ignore' properties when adding a
submodule with the "--attach" switch is to give a convenient default behaviour.
No other properties are set: the repository responsible will still be required
to configure a different 'submodule.<name>.update' behaviour separetely, if he
wants that.

When updating, using the '--attach' switch or operating in a repository with
'submodule.<name>.attach' set to 'true' will:
- checkout a branch with an attached HEAD if the repository was just cloned;
- perform a fast-forward only merge of changes if it's a 'checkout' update,
keeping the HEAD attached;
- reattach the HEAD prior performing a 'merge', 'rebase' or '!command' update
operation if the HEAD was found detached.

'--attach' or 'submodule.<name>.attach' set to true also implies '--remote', as
it's needed the origin HEAD sha1 to verify the current HEAD state.

A '--detach' switch is also available. Using the '--detach' switch or
operating in a repository with 'submodule.<name>.attach' set to 'false' during
update will:
- checkout a detached HEAD if the repository was just cloned (same behaviour as
before);
- detach the HEAD prior performing a 'merge', 'rebase' or '!command' update
operation if the HEAD was found attached.

'submodule.<name>.attach' works the same way as 'submodule.<name>.update'
property: git copies the values found in ".gitmodules" in ".git/config" when
performing an "init" command. "update" looks for the values in ".git/config"
only.

'--attach' and '--detach' switches override an opposite behaviour of 'submodule.<name>.attach'
properties.

The patch is small (touches only git-submodule.sh) and 100% additive with
respect to currently documented behaviour: when using "add" and "update"
commands without the introduced switches and properties, git shall operate as
before. As a bonus (but this was done to ease conditionals and keep the code
clean) it also clarifies and validates the content of 'submodule.<name>.update'
during 'update' command, warning the user if it's not one of the supported
values 'checkout', 'merge', 'rebase' and 'none'. Please note that 'checkout'
update command was documented in upstream "Documentation/gitmodules.txt" [2] as
a valid 'submodule.<name>.update' value and code in upstream "git-submodule.sh"
implicitly assumes it as recognized value. "Documentation/git-submodule.txt"
doesn't mention it properly and I guess this is the reason why it wasn't
considered for the validation in [1] patch.

Using this patch, the previous workflow becomes:

# Maintainer
$ git submodule add --branch "master-project1" --attach <repository> <path>
$ git commit -m "Added submodule"
$ git push

# Developer
$ git pull
$ git submodule init
$ git submodule update

Is there interest in supporting this workflow and seeing this patch applied?

Thanks,
Francesco

[1] http://marc.info/?l=git&m=138610752125816&w=2
[2] Documentation/gitmodules.txt: "If 'checkout' (the default)..."

Signed-off-by: Francesco Pretto <ceztko@xxxxxxxxx>
---
 Documentation/git-submodule.txt |  37 ++++++---
 Documentation/gitmodules.txt    |  11 ++-
 git-submodule.sh                | 172 +++++++++++++++++++++++++++++++++++++---
 3 files changed, 197 insertions(+), 23 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index bfef8a0..452376d 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -10,13 +10,14 @@ SYNOPSIS
 --------
 [verse]
 'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
-	      [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]
+	      [--reference <repository>] [--attach] [--depth <depth>]
+	      [--] <repository> [<path>]
 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
-	      [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]
-	      [--merge] [--recursive] [--] [<path>...]
+	      [-f|--force] [--rebase] [--reference <repository>] [--attach | --detach]
+	      [--depth <depth>] [--merge] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
 	      [commit] [--] [<path>...]
 'git submodule' [--quiet] foreach [--recursive] <command>
@@ -107,6 +108,10 @@ is the superproject and submodule repositories will be kept
 together in the same relative location, and only the
 superproject's URL needs to be provided: git-submodule will correctly
 locate the submodule using the relative URL in .gitmodules.
++
+If `--attach` is specified, the submodule will be registered to be
+checked out with an an attached HEAD. Also `submodule.<name>.attach` will
+be set to `true` and `submodule.<name>.ignore` will be set to `all`.
 
 status::
 	Show the status of the submodules. This will print the SHA-1 of the
@@ -156,12 +161,15 @@ it contains local modifications.
 update::
 	Update the registered submodules, i.e. clone missing submodules and
 	checkout the commit specified in the index of the containing repository.
-	This will make the submodules HEAD be detached unless `--rebase` or
-	`--merge` is specified or the key `submodule.$name.update` is set to
-	`rebase`, `merge` or `none`. `none` can be overridden by specifying
-	`--checkout`. Setting the key `submodule.$name.update` to `!command`
-	will cause `command` to be run. `command` can be any arbitrary shell
-	command that takes a single argument, namely the sha1 to update to.
+	This will make the submodules HEAD be detached unless `--attach` is
+	specified or `submodule.$name.attach` is set to `true`. The last setting
+	can always be overridden specifying `--detach`. Update mode can be
+	selected specifying `--checkout`, `--rebase` or `--merge` switches
+	or setting the key `submodule.$name.update` to `checkout`, `rebase`,
+	`merge` or `none`. `none` will cause the submodule to be skipped during
+	the update. Setting the key `submodule.$name.update` to `!command` will
+	cause `command` to be run. `command` can be any arbitrary shell command
+	that takes a single argument, namely the sha1 to update to.
 +
 If the submodule is not yet initialized, and you just want to use the
 setting as stored in .gitmodules, you can automatically initialize the
@@ -270,6 +278,17 @@ OPTIONS
 	be overridden by setting the `submodule.<name>.branch` option in
 	either `.gitmodules` or `.git/config` (with `.git/config` taking
 	precedence).
+
+--attach::
+	This option is only valid for the add and update commands. Cause the
+	result of an add or update operation to be an attached HEAD. In the
+	update command , if `submodule.<name>.branch` is not set, it will
+	default to `master`. Note: for the update command `--attach` also
+	implies `--remote`.
+
+--detach::
+	This option is only valid for the update command. Cause the result
+	of the update operation to be forcedly a detached HEAD.
 +
 This works for any of the supported update procedures (`--checkout`,
 `--rebase`, etc.).  The only change is the source of the target SHA-1.
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index f7be93f..e6c3360 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -37,8 +37,10 @@ submodule.<name>.url::
 
 submodule.<name>.update::
 	Defines what to do when the submodule is updated by the superproject.
-	If 'checkout' (the default), the new commit specified in the
-	superproject will be checked out in the submodule on a detached HEAD.
+	If 'checkout' (the default), the new commit (or the branch, when using
+	the '--attach' switch or the 'submodule.<name>.attach' property is set
+	to 'true' during an update operation) specified in the superproject will
+	be checked out in the submodule.
 	If 'rebase', the current branch of the submodule will be rebased onto
 	the commit specified in the superproject. If 'merge', the commit
 	specified in the superproject will be merged into the current branch
@@ -54,6 +56,11 @@ submodule.<name>.branch::
 	If the option is not specified, it defaults to 'master'.  See the
 	`--remote` documentation in linkgit:git-submodule[1] for details.
 
+submodule.<name>.attach::
+	Determine if the update operation will produce a detached HEAD or not.
+	Valid values are `true` or `false`. If the property is set to `true`
+	and `submodule.<name>.branch`, it will default to `master`
+
 submodule.<name>.fetchRecurseSubmodules::
 	This option can be used to control recursive fetching of this
 	submodule. If this option is also present in the submodules entry in
diff --git a/git-submodule.sh b/git-submodule.sh
index 2677f2e..3951fa2 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -5,11 +5,11 @@
 # Copyright (c) 2007 Lars Hjemli
 
 dashless=$(basename "$0" | sed -e 's/-/ /')
-USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--] <repository> [<path>]
+USAGE="[--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--attach] [--] <repository> [<path>]
    or: $dashless [--quiet] status [--cached] [--recursive] [--] [<path>...]
    or: $dashless [--quiet] init [--] [<path>...]
    or: $dashless [--quiet] deinit [-f|--force] [--] <path>...
-   or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--merge] [--recursive] [--] [<path>...]
+   or: $dashless [--quiet] update [--init] [--remote] [-N|--no-fetch] [-f|--force] [--rebase] [--reference <repository>] [--attach | --detach] [--merge] [--recursive] [--] [<path>...]
    or: $dashless [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]
    or: $dashless [--quiet] foreach [--recursive] <command>
    or: $dashless [--quiet] sync [--recursive] [--] [<path>...]"
@@ -36,6 +36,7 @@ update=
 prefix=
 custom_name=
 depth=
+attach=
 
 # The function takes at most 2 arguments. The first argument is the
 # URL that navigates to the submodule origin repo. When relative, this URL
@@ -352,6 +353,9 @@ cmd_add()
 			custom_name=$2
 			shift
 			;;
+		--attach)
+			attach="true"
+			;;
 		--depth)
 			case "$2" in '') usage ;; esac
 			depth="--depth=$2"
@@ -475,8 +479,17 @@ Use -f if you really want to add it." >&2
 			cd "$sm_path" &&
 			# ash fails to wordsplit ${branch:+-b "$branch"...}
 			case "$branch" in
-			'') git checkout -f -q ;;
-			?*) git checkout -f -q -B "$branch" "origin/$branch" ;;
+			'')
+				git checkout -f -q
+				;;
+			?*)
+				if test -n "$attach"
+				then
+					git checkout -f -q "$branch"
+				else
+					git checkout -f -q -B "$branch" "origin/$branch"
+				fi
+				;;
 			esac
 		) || die "$(eval_gettext "Unable to checkout submodule '\$sm_path'")"
 	fi
@@ -491,6 +504,12 @@ Use -f if you really want to add it." >&2
 	then
 		git config -f .gitmodules submodule."$sm_name".branch "$branch"
 	fi &&
+	if test -n "$attach"
+	then
+		# We'll stay stick to the HEAD, no need to track revision sha1
+		git config -f .gitmodules submodule."$sm_name".attach "true"
+		git config -f .gitmodules submodule."$sm_name".ignore "all"
+	fi &&
 	git add --force .gitmodules ||
 	die "$(eval_gettext "Failed to register submodule '\$sm_path'")"
 }
@@ -622,7 +641,7 @@ cmd_init()
 		   test -z "$(git config submodule."$name".update)"
 		then
 			case "$upd" in
-			rebase | merge | none)
+			checkout | rebase | merge | none)
 				;; # known modes of updating
 			*)
 				echo >&2 "warning: unknown update mode '$upd' suggested for submodule '$name'"
@@ -632,6 +651,23 @@ cmd_init()
 			git config submodule."$name".update "$upd" ||
 			die "$(eval_gettext "Failed to register update mode for submodule path '\$displaypath'")"
 		fi
+
+		# Copy "attach" setting when it is not set yet
+		if attached="$(git config -f .gitmodules submodule."$name".attach)" &&
+		   test -n "$attached" &&
+		   test -z "$(git config submodule."$name".attach)"
+		then
+			case "$attached" in
+			true | false)
+				;; # Valid attach flag values
+			*)
+				echo >&2 "warning: invalid attach flag value for submodule '$name'"
+				upd=none
+				;;
+			esac
+			git config submodule."$name".attach "$attached" ||
+			die "$(eval_gettext "Failed to register attached option for submodule path '\$displaypath'")"
+		fi
 	done
 }
 
@@ -750,6 +786,14 @@ cmd_update()
 		--reference=*)
 			reference="$1"
 			;;
+		--attach)
+			if test "$attach" = "false" ; then usage ; fi
+			attach="true"
+			;;
+		--detach)
+			if test "$attach" = "true" ; then usage ; fi
+			attach="false"
+			;;
 		-m|--merge)
 			update="merge"
 			;;
@@ -800,11 +844,44 @@ cmd_update()
 		name=$(module_name "$sm_path") || exit
 		url=$(git config submodule."$name".url)
 		branch=$(get_submodule_config "$name" branch master)
+		if test -n "$attach"
+		then
+			attach_module=$attach
+		else
+			attach_module=$(git config submodule."$name".attach)
+			case "$attach_module" in
+			'')
+				;; # Unset attach flag
+			true|false)
+				;; # Valid attach flag values
+			*)
+				echo >&2 "warning: invalid attach flag value for submodule '$name'"
+				attach_module=
+				;;
+			esac
+		fi
+		if test "$attach_module" = "false"
+		then
+			# Normalize attach 'false' flag value
+			attach_module=
+		fi
 		if ! test -z "$update"
 		then
 			update_module=$update
 		else
 			update_module=$(git config submodule."$name".update)
+			case "$update_module" in
+			'')
+				;; # Unset update mode
+			checkout | rebase | merge | none)
+				;; # Known update modes
+			!*)
+				;; # Custom update command
+			*)
+				update_module=
+				echo >&2 "warning: invalid update mode for submodule '$name'"
+				;;
+			esac
 		fi
 
 		displaypath=$(relative_path "$prefix$sm_path")
@@ -836,7 +913,7 @@ Maybe you want to use 'update --init'?")"
 			die "$(eval_gettext "Unable to find current revision in submodule path '\$displaypath'")"
 		fi
 
-		if test -n "$remote"
+		if test -n "$remote" -o -n "$attach_module"
 		then
 			if test -z "$nofetch"
 			then
@@ -850,7 +927,16 @@ Maybe you want to use 'update --init'?")"
 			die "$(eval_gettext "Unable to find current ${remote_name}/${branch} revision in submodule path '\$sm_path'")"
 		fi
 
-		if test "$subsha1" != "$sha1" -o -n "$force"
+		head_rev_ref=$(clear_local_git_env; cd "$sm_path" && git rev-parse --abbrev-ref HEAD) ||
+		die "$(eval_gettext "Unable to determine revision ref in submodule path '\$sm_path'")"
+		if test "$head_rev_ref" = "HEAD"
+		then
+			# Determine if the HEAD is detached
+			head_detached="true"
+		fi
+
+		if test "$subsha1" != "$sha1" || test -n "$attach_module" -a -n "$head_detached" ||
+			test -z "$attach_module" -a -z "$head_detached" || test -n "$force"
 		then
 			subforce=$force
 			# If we don't already have a -f flag and the submodule has never been checked out
@@ -870,40 +956,102 @@ Maybe you want to use 'update --init'?")"
 			fi
 
 			# Is this something we just cloned?
+			just_cloned=
 			case ";$cloned_modules;" in
 			*";$name;"*)
 				# then there is no local change to integrate
-				update_module= ;;
+				update_module="checkout"
+				just_cloned=yes
+				;;
 			esac
 
+			if test -z "$update_module"
+			then
+				# Fallback to checkout
+				update_module="checkout"
+			fi
+			
+			command_pre=:
+			suffix_pre=
+			if test "$update_module" = "checkout"
+			then
+				if test -n "$attach_module" -a -z "$just_cloned"
+				then
+					# We need to attach to the HEAD/switch the branch prior
+					# performing any fast-forward update
+					command_pre="git checkout $subforce -q"
+					suffix_pre=$branch
+				fi
+			else
+				if test -n "$attach_module" -a -n "$head_detached"
+				then
+					# We need to reattach to the head
+					command_pre="git checkout $subforce -q"
+					suffix_pre=$branch
+				elif test -z "$attach_module" -a -z "$head_detached"
+				then
+					# We need to detach from the head
+					command_pre="git checkout $subforce -q"
+					suffix_pre=$sha1
+				fi
+			fi
+
 			must_die_on_failure=
+			custom_update=
+			suffix=
 			case "$update_module" in
 			rebase)
 				command="git rebase"
+				suffix=$sha1
 				die_msg="$(eval_gettext "Unable to rebase '\$sha1' in submodule path '\$displaypath'")"
 				say_msg="$(eval_gettext "Submodule path '\$displaypath': rebased into '\$sha1'")"
 				must_die_on_failure=yes
 				;;
 			merge)
 				command="git merge"
+				suffix=$sha1
 				die_msg="$(eval_gettext "Unable to merge '\$sha1' in submodule path '\$displaypath'")"
 				say_msg="$(eval_gettext "Submodule path '\$displaypath': merged in '\$sha1'")"
 				must_die_on_failure=yes
 				;;
+			checkout)
+				if test -n "$attach_module"
+				then
+					if test -n "$just_cloned"
+					then
+						command="git checkout $subforce -q"
+						suffix=$branch
+					else
+						# Perform a fast-forward only merge of the origin
+						command="git merge $subforce --ff-only"
+						suffix="origin/$branch"
+					fi
+					die_msg="$(eval_gettext "Unable to checkout banch '\$branch' in submodule path '\$displaypath'")"
+					say_msg="$(eval_gettext "Submodule path '\$displaypath': checked out branch '\$branch'")"
+				else
+					command="git checkout $subforce -q"
+					suffix=$sha1
+					die_msg="$(eval_gettext "Unable to checkout '\$sha1' in submodule path '\$displaypath'")"
+					say_msg="$(eval_gettext "Submodule path '\$displaypath': checked out '\$sha1'")"
+				fi
+				;;
 			!*)
 				command="${update_module#!}"
+				suffix=$sha1
 				die_msg="$(eval_gettext "Execution of '\$command \$sha1' failed in submodule  path '\$prefix\$sm_path'")"
 				say_msg="$(eval_gettext "Submodule path '\$prefix\$sm_path': '\$command \$sha1'")"
 				must_die_on_failure=yes
+				custom_update=yes
 				;;
 			*)
-				command="git checkout $subforce -q"
-				die_msg="$(eval_gettext "Unable to checkout '\$sha1' in submodule path '\$displaypath'")"
-				say_msg="$(eval_gettext "Submodule path '\$displaypath': checked out '\$sha1'")"
+				# Valid user configurable update modes are already filtered above
+				die "$(eval_gettext "Unexpected update mode in the current flow")"
 				;;
 			esac
 
-			if (clear_local_git_env; cd "$sm_path" && $command "$sha1")
+			if (clear_local_git_env; cd "$sm_path" &&
+				$command_pre "$suffix_pre" &&
+				$command "$suffix")
 			then
 				say "$say_msg"
 			elif test -n "$must_die_on_failure"
-- 
1.8.5.2.227.g53f3478.dirty

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]