git-submodule - Add 'foreach' subcommand

submodule foreach <command-list> will execute the list of commands in
each currently checked out submodule directory. The list of commands
is arbitrary as long as it is acceptable to sh. The variables '$path'
and '$sha1' are availble to the command-list, defining the submodule
path relative to the superproject and the submodules's commitID as
recorded in the superproject (this may be different than HEAD in the
submodule).

This utility is inspired by a number of threads on the mailing list
looking for ways to better integrate submodules in a tree and work
with them as a unit. This could include fetching a new branch in each
from a given source, or possibly checking out a given named branch in
each. Currently, there is no consensus as to what additional commands
should be implemented in the porcelain, requiring all users whose needs
exceed that of git-submodule to do their own scripting. The foreach
command is intended to support such scripting, and in particular does
no error checking and produces no output, thus allowing end users
complete control over any information printed out and over what
constitutes an error. The processing does terminate if the command-list
returns an error, but processing can easily be forced for all
submodules be terminating the list with ';true'.

Signed-off-by: Mark Levedahl <mlevedahl@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Documentation/git-submodule.txt

@@ -14,6 +14,7 @@ SYNOPSIS
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] update [--init] [--] [<path>...]
 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
+'git submodule' [--quiet] foreach <command>
 
 
 DESCRIPTION
@@ -123,6 +124,22 @@ summary::
 	in the submodule between the given super project commit and the
 	index or working tree (switched by --cached) are shown.
 
+foreach::
+	Evaluates an arbitrary shell command in each checked out submodule.
+	The command has access to the variables $path and $sha1:
+	$path is the name of the submodule directory relative to the
+	superproject, and $sha1 is the commit as recorded in the superproject.
+	Any submodules defined in the superproject but not checked out are
+	ignored by this command. Unless given --quiet, foreach prints the name
+	of each submodule before evaluating the command.
+	A non-zero return from the command in any submodule causes
+	the processing to terminate. This can be overridden by adding '|| :'
+	to the end of the command.
++
+As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will
+show the path and currently checked out commit for each submodule.
+
+
 OPTIONS
 -------
 -q::

git-submodule.sh

@@ -6,7 +6,7 @@
 
 USAGE="[--quiet] [--cached] \
 [add <repo> [-b branch] <path>]|[status|init|update [-i|--init]|summary [-n|--summary-limit <n>] [<commit>]] \
-[--] [<path>...]"
+[--] [<path>...]|[foreach <command>]"
 OPTIONS_SPEC=
 . git-sh-setup
 require_work_tree
@@ -198,6 +198,26 @@ cmd_add()
 	die "Failed to register submodule '$path'"
 }
 
+#
+# Execute an arbitrary command sequence in each checked out
+# submodule
+#
+# $@ = command to execute
+#
+cmd_foreach()
+{
+	git ls-files --stage | grep '^160000 ' |
+	while read mode sha1 stage path
+	do
+		if test -e "$path"/.git
+		then
+			say "Entering '$path'"
+			(cd "$path" && eval "$@") ||
+			die "Stopping at '$path'; script returned non-zero status."
+		fi
+	done
+}
+
 #
 # Register submodules in .git/config
 #
@@ -583,7 +603,7 @@ cmd_status()
 while test $# != 0 && test -z "$command"
 do
 	case "$1" in
-	add | init | update | status | summary)
+	add | foreach | init | update | status | summary)
 		command=$1
 		;;
 	-q|--quiet)