[PATCH v3 1/4] git-submodule: New subcommand 'summary' (1) - code framework

[PATCH v3 1/4] git-submodule: New subcommand 'summary' (1) - code framework

[Ping Yin]

Following patches will teach git-submodule a new subcommand 'summary' to
show commit summary of user-cared (i.e. checked out) submodules between
a given super project commit (default HEAD) and working tree
(or index, switched by --cached).

This patch just introduces the framework and shows submodules modified
as follows.

--------------------------------------------
 $ git submodule summary
 # Submodules modifiled: sm1 sm2 sm3 sm4 sm5
 #
--------------------------------------------

Signed-off-by: Ping Yin <pkufranky@gmail.com>
---
 git-submodule.sh |   66 +++++++++++++++++++++++++++++++++++++++++++++++++----
 1 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/git-submodule.sh b/git-submodule.sh
index a6aaf40..787d083 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -4,7 +4,7 @@
 #
 # Copyright (c) 2007 Lars Hjemli
 
-USAGE='[--quiet] [--cached] [add <repo> [-b branch]|status|init|update] [--] [<path>...]'
+USAGE='[--quiet] [--cached] [add <repo> [-b branch]|status|init|update|summary [<commit>]] [--] [<path>...]'
 OPTIONS_SPEC=
 . git-sh-setup
 require_work_tree
@@ -320,7 +320,63 @@ set_name_rev () {
 	) )
 	test -z "$revname" || revname=" ($revname)"
 }
+#
+# Show commit summary for submodules in index or working tree
+#
+# If '--cached' is given, show summary between index and given commit,
+# or between working tree and given commit
+#
+# $@ = [commit (default 'HEAD'),] requested paths (default all)
+#
+cmd_summary() {
+	# parse $args after "submodule ... summary".
+	while test $# -ne 0
+	do
+		case "$1" in
+		--cached)
+			cached="$1"
+			;;
+		--)
+			shift
+			break
+			;;
+		-*)
+			usage
+			;;
+		*)
+			break
+			;;
+		esac
+		shift
+	done
 
+	if rev=$(git rev-parse --verify "$1^0" 2>/dev/null)
+	then
+		head=$rev
+		shift
+	else
+		head=HEAD
+	fi
+
+	cd_to_toplevel
+	# Get modified modules cared by user
+	modules=$(git diff-index $cached --raw $head -- "$@" |
+		grep -e '^:160000' -e '^:[0-7]* 160000' |
+		while read mod_src mod_dst sha1_src sha1_dst status name
+		do
+			# Always show modules deleted or type-changed (blob<->module)
+			test $status = D -o $status = T && echo "$name" && continue
+			# Also show added or modified modules which are checked out
+			GIT_DIR="$name/.git" git-rev-parse --git-dir >/dev/null 2>&1 &&
+			echo "$name"
+		done
+	)
+
+	# TODO: quote module names containing space or tab
+	test -n "$modules" &&
+	echo "# Submodules modified: "$modules &&
+	echo "#"
+}
 #
 # List all submodules, prefixed with:
 #  - submodule not initialized
@@ -391,7 +447,7 @@ cmd_status()
 while test $# != 0 && test -z "$command"
 do
 	case "$1" in
-	add | init | update | status)
+	add | init | update | status | summary)
 		command=$1
 		;;
 	-q|--quiet)
@@ -406,7 +462,7 @@ do
 		branch="$2"; shift
 		;;
 	--cached)
-		cached=1
+		cached="$1"
 		;;
 	--)
 		break
@@ -430,8 +486,8 @@ then
 	usage
 fi
 
-# "--cached" is accepted only by "status"
-if test -n "$cached" && test "$command" != status
+# "--cached" is accepted only by "status" and "summary"
+if test -n "$cached" && test "$command" != status -a "$command" != summary
 then
 	usage
 fi
-- 
1.5.4.3.347.g5314c

[PATCH v3 2/4] git-submodule: New subcommand 'summary' (2) - show commit summary

[Ping Yin]

This patch does the hard work to show submodule commit summary.

For a submodule in question, a series of commits will be shown as the path
from the src commit to the dst commit, where the src commit is from the given
super project commit, and the dst commit is from the index or working tree
(switched by --cached).

Example: commit summary for modified submodules sm1-sm5.
--------------------------------------------
 $ git submodule summary
 # Submodules modifiled: sm1 sm2 sm3 sm4 sm5
 #
 # * sm1 354cd45...3f751e5:
 #   <one line message for C
 #   <one line message for B
 #   >one line message for D
 #   >one line message for E
 #
 # * sm2 5c8bfb5...000000:
 #   <one line message for F
 #
 # * sm3 354cd45...3f751e5:
 #   Warn: sm3 doesn't contain commit 354cd45
 #
 # * sm4 354cd34(submodule)->235efa(blob):
 #   <one line message for G
 #
 # * sm5 354cd34(blob)->235efa(submodule):
 #   >one line message for H
 #
--------------------------------------------

sm1 has commit C as src (given commit or HEAD) and commit E as dst (index
or working tree) as following picture shows.
	--A-->B-->C (in src:354cd45)
	  \
	   -->D-->E (in dst:3f751e5)

The 'Submodules modified' section for sm1 shows how to change sm1 from
src commit C to dst commit E: firstly backward (<) to commit A from
commit C via commit B, and then forward (>) to commit E via commit D.

Illustration for output of deleted sm2 is similar.

sm4 and sm5 are submodules with typechanging (blob<->submodule).

If the src/dst commit for a submodule is missing in the submodule
directory, a warning will be issued (sm3 falls into this case)
except in two cases where the submodule directory is deleted
(type 'D') or typechanged to blob (one case of type 'T').

Signed-off-by: Ping Yin <pkufranky@gmail.com>
---
 git-submodule.sh |   73 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 72 insertions(+), 1 deletions(-)

diff --git a/git-submodule.sh b/git-submodule.sh
index 787d083..3313d6c 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -375,7 +375,78 @@ cmd_summary() {
 	# TODO: quote module names containing space or tab
 	test -n "$modules" &&
 	echo "# Submodules modified: "$modules &&
-	echo "#"
+	echo "#" &&
+	git diff-index $cache_option --raw $head -- $modules |
+	grep -e '^:160000' -e '^:[0-7]* 160000' |
+	cut -c2- |
+	while read mod_src mod_dst sha1_src sha1_dst status name
+	do
+		if test -z "$cache_option" &&
+			test $sha1_dst = 0000000000000000000000000000000000000000 &&
+			( GIT_DIR="$name/.git" git rev-parse HEAD ) >/dev/null 2>&1
+		then
+			sha1_dst=$(GIT_DIR="$name/.git" git rev-parse HEAD)
+		fi
+		check_src=$(echo $mod_src | grep 160000)
+		check_dst=$(echo $mod_dst | grep 160000)
+		errmsg=
+		missing_src=
+		missing_dst=
+
+		test -z "$check_src" ||
+		GIT_DIR="$name/.git" git-rev-parse --verify $sha1_src >/dev/null 2>&1 ||
+		missing_src=t
+
+		test -z "$check_dst" ||
+		GIT_DIR="$name/.git" git-rev-parse --verify $sha1_dst >/dev/null 2>&1 ||
+		missing_dst=t
+
+		case "$missing_src,$missing_dst" in
+		t,)
+			errmsg="  Warn: $name doesn't contain commit $sha1_src"
+			;;
+		,t)
+			errmsg="  Warn: $name doesn't contain commit $sha1_dst"
+			;;
+		t,t)
+			errmsg="  Warn: $name doesn't contain commits $sha1_src and $sha1_dst"
+			;;
+		*)
+			left=
+			right=
+			test -n "$check_src" &&
+			left=$(GIT_DIR="$name/.git" git log --pretty=format:"  <%s" \
+			${check_dst:+$sha1_dst..}$sha1_src 2>/dev/null)
+
+			test -n "$check_dst" &&
+			right=$(GIT_DIR="$name/.git" git log --reverse --pretty=format:"  >%s" \
+			${check_src:+$sha1_src..}$sha1_dst 2>/dev/null)
+			;;
+		esac
+
+		sha1_src=$(echo $sha1_src | cut -c1-7)
+		sha1_dst=$(echo $sha1_dst | cut -c1-7)
+		if test $status = T
+		then
+			if test $mod_dst = 160000
+			then
+				echo "* $name $sha1_src(blob)->$sha1_dst(submodule):"
+			else
+				echo "* $name $sha1_src(submodule)->$sha1_dst(blob):"
+			fi
+		else
+			echo "* $name $sha1_src...$sha1_dst:"
+		fi
+		if test -n "$errmsg"
+		then
+			# Don't give error msg for modification whose dst is not submodule, i.e. deleted or changed to blob
+			test $mod_dst = 160000 && echo "$errmsg"
+		else
+			test -n "$left" && echo "$left"
+			test -n "$right" && echo "$right"
+		fi
+		echo
+	done | sed -e 's/^/# /'
 }
 #
 # List all submodules, prefixed with:
-- 
1.5.4.3.347.g5314c

Re: [PATCH v3 2/4] git-submodule: New subcommand 'summary' (2) - show commit summary

[Junio C Hamano]

Ping Yin <pkufranky@gmail.com> writes:

> Example: commit summary for modified submodules sm1-sm5.
> --------------------------------------------
>  $ git submodule summary
>  # Submodules modifiled: sm1 sm2 sm3 sm4 sm5
>  #
>  # * sm1 354cd45...3f751e5:
>  #   <one line message for C
>  #   <one line message for B
>  #   >one line message for D
>  #   >one line message for E
> ...
> 	--A-->B-->C (in src:354cd45)
> 	  \
> 	   -->D-->E (in dst:3f751e5)

The ordering of the commits in the above list is (1) unnatural and (2)
does not match what you would see with "log --left-right --topo-order
C...E".

I do not think "it shows the path to move from C to E" justifies it.  If
you are showing them as a linear list (which you cannot avoid if you are
doing a sequence of one-line description), you cannot represent such a
"path" anyway (think "merge").  If an appliance project rebinds kernel/
path from a project based on linux-2.4 to linux-2.6 while upgrading, such
a "path" may not even exist.

I think I've already said the above to your initial round.  It is a bit
dissapointing to see none of the comments were addressed and makes me
wonder if I have wasted my time reviewing them again.

It also is unnerving that newly added and deleted submodule results in the
full history display.  It would be assuring to be able to see and verify
what the top commit is (or was in "deleted" case) while you are commiting,
but I do not see a reason to show more than that.

I do not think "then set the limit to 1" is a valid answer to that
concern.  Wanting to see a dozen top commits in each for a modified
submodule would be sensible (and 3/4 may implement such a limit) but even
then showing dozen top commits for new/deleted at the same time would be
just an added noise.  Is it really necessary to show more than the top for
new/deleted case?

Re: [PATCH v3 2/4] git-submodule: New subcommand 'summary' (2) - show commit summary

[Ping Yin]

On Thu, Mar 6, 2008 at 7:57 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Ping Yin <pkufranky@gmail.com> writes:
>
>  > Example: commit summary for modified submodules sm1-sm5.
> >       --A-->B-->C (in src:354cd45)
>  >         \
>  >          -->D-->E (in dst:3f751e5)
>
>  The ordering of the commits in the above list is (1) unnatural and (2)
>  does not match what you would see with "log --left-right --topo-order
>  C...E".
>
>  I do not think "it shows the path to move from C to E" justifies it.  If
>  you are showing them as a linear list (which you cannot avoid if you are
>  doing a sequence of one-line description), you cannot represent such a
>  "path" anyway (think "merge").  If an appliance project rebinds kernel/
>  path from a project based on linux-2.4 to linux-2.6 while upgrading, such
>  a "path" may not even exist.
>
Good point to show 'log --left-right --topo-order' is better

>  I think I've already said the above to your initial round.  It is a bit
>  dissapointing to see none of the comments were addressed and makes me
>  wonder if I have wasted my time reviewing them again.

Sorry i lost your comments. Maybe it's a long time ago, i will revisit them.

>
>  It also is unnerving that newly added and deleted submodule results in the
>  full history display.  It would be assuring to be able to see and verify
>  what the top commit is (or was in "deleted" case) while you are commiting,
>  but I do not see a reason to show more than that.
>
>  I do not think "then set the limit to 1" is a valid answer to that
>  concern.  Wanting to see a dozen top commits in each for a modified
>  submodule would be sensible (and 3/4 may implement such a limit) but even
>  then showing dozen top commits for new/deleted at the same time would be
>  just an added noise.  Is it really necessary to show more than the top for
>  new/deleted case?
>
Actually, not make much sense to show many commits in delete or add
case. I think showing 2 (the head and tail one) should make more sense
since the head one would be "Initial add ..." in many cases which
doesn't make much sense for the user.

I will resend my patches after taking considering all of your
suggestion today or tommorow.



-- 
Ping Yin

Re: [PATCH v3 2/4] git-submodule: New subcommand 'summary' (2) - show commit summary

[Junio C Hamano]

"Ping Yin" <pkufranky@gmail.com> writes:

> ... I think showing 2 (the head and tail one) should make more sense
> since the head one would be "Initial add ..." in many cases which
> doesn't make much sense for the user.

Why would you want to see the bottom one?  I still don't understand.

And I do not mean this as a rhetorical question.  I am here to learn and
I would like to make sure that I do not make a suggestion based on wrong
understanding of what the user wants to see.

I probably am lacking imagination to think of a good use scenario that
showing the bottom one would be useful to the user, and you as the author
of this patch must thought about what the user want much more than me.

Re: [PATCH v3 2/4] git-submodule: New subcommand 'summary' (2) - show commit summary

[Ping Yin]

On Thu, Mar 6, 2008 at 12:10 PM, Junio C Hamano <gitster@pobox.com> wrote:
> "Ping Yin" <pkufranky@gmail.com> writes:
>
>  > ... I think showing 2 (the head and tail one) should make more sense
>
> > since the head one would be "Initial add ..." in many cases which
>  > doesn't make much sense for the user.
>
>  Why would you want to see the bottom one?  I still don't understand.
>
>  And I do not mean this as a rhetorical question.  I am here to learn and
>  I would like to make sure that I do not make a suggestion based on wrong
>  understanding of what the user wants to see.
>
>  I probably am lacking imagination to think of a good use scenario that
>  showing the bottom one would be useful to the user, and you as the author
>  of this patch must thought about what the user want much more than me.
>
Showing the bottom one can give the user an impression where
the submodules goes at first glance if the user is familiar with the
developing progress of the submodule.

However, i don't have very strong point on this and just think it
seems good when
i type 'git log'  (i have make the summary go into the commit message)



-- 
Ping Yin

Re: [PATCH v3 2/4] git-submodule: New subcommand 'summary' (2) - show commit summary

[Junio C Hamano]

"Ping Yin" <pkufranky@gmail.com> writes:

>>  Why would you want to see the bottom one?  I still don't understand.
>>
>>  And I do not mean this as a rhetorical question.  I am here to learn and
>>  I would like to make sure that I do not make a suggestion based on wrong
>>  understanding of what the user wants to see.
>>
>>  I probably am lacking imagination to think of a good use scenario that
>>  showing the bottom one would be useful to the user, and you as the author
>>  of this patch must thought about what the user want much more than me.
>>
> Showing the bottom one can give the user an impression where
> the submodules goes at first glance if the user is familiar with the
> developing progress of the submodule.

I think you are talking about the top one (the latest commit), and we both
know that is interesting information to show.  I was asking about the most
ancient one, which often is "Initial version of frotz."

Re: [PATCH v3 2/4] git-submodule: New subcommand 'summary' (2) - show commit summary

[Ping Yin]

On Thu, Mar 6, 2008 at 6:42 PM, Junio C Hamano <gitster@pobox.com> wrote:
> "Ping Yin" <pkufranky@gmail.com> writes:
>
>
> >>  Why would you want to see the bottom one?  I still don't understand.
>  >>
>  >>  And I do not mean this as a rhetorical question.  I am here to learn and
>  >>  I would like to make sure that I do not make a suggestion based on wrong
>  >>  understanding of what the user wants to see.
>  >>
>  >>  I probably am lacking imagination to think of a good use scenario that
>  >>  showing the bottom one would be useful to the user, and you as the author
>  >>  of this patch must thought about what the user want much more than me.
>  >>
>  > Showing the bottom one can give the user an impression where
>  > the submodules goes at first glance if the user is familiar with the
>  > developing progress of the submodule.
>
>  I think you are talking about the top one (the latest commit), and we both
>  know that is interesting information to show.  I was asking about the most
>  ancient one, which often is "Initial version of frotz."
>
Right, we have misunderstood each other in the 'bottom'  word. I thought
you propose to keep the initial one, and i said the latest one make much
sense than the initial one.

Now we agree on that keeping the latest commit is enough.



-- 
Ping Yin

[PATCH v3 3/4] git-submodule: New subcommand 'summary' (3) - limit summary size

[Ping Yin]

This patch teaches git-submodule an option '--summary-limit|-n <number>'
to limit number of commits in total for the summary. Number 0 will disable
summary and minus number means unlimted (the default).

For beauty and clarification, the fork-point (i.e. the last commits for
both backward and forward sections) will always be shown disregarding the
given limit. So actual summary size may be greater than the given limit.

'git submodule summary -n 2 sm1' and 'git submodule summary -n 3 sm1'
will show the same in the super project mentioned in last patch.

---------------------------------------
 $ git submodule summary -n 2 sm1
 # Submodules modifiled: sm1
 #
 # * sm1 354cd45...3f751e5:
 #   <one line message for C
 #   <one line message for B
 #   >...
 #   >one line message for E
 #
---------------------------------------

Signed-off-by: Ping Yin <pkufranky@gmail.com>
---
 git-submodule.sh |   65 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/git-submodule.sh b/git-submodule.sh
index 3313d6c..dfd2952 100755
--- a/git-submodule.sh
+++ b/git-submodule.sh
@@ -4,7 +4,9 @@
 #
 # Copyright (c) 2007 Lars Hjemli
 
-USAGE='[--quiet] [--cached] [add <repo> [-b branch]|status|init|update|summary [<commit>]] [--] [<path>...]'
+USAGE="[--quiet] [--cached] \
+[add <repo> [-b branch]|status|init|update|summary [-n|--summary-limit <n>] [<commit>]] \
+[--] [<path>...]"
 OPTIONS_SPEC=
 . git-sh-setup
 require_work_tree
@@ -329,6 +331,8 @@ set_name_rev () {
 # $@ = [commit (default 'HEAD'),] requested paths (default all)
 #
 cmd_summary() {
+	summary_limit=-1
+
 	# parse $args after "submodule ... summary".
 	while test $# -ne 0
 	do
@@ -336,6 +340,15 @@ cmd_summary() {
 		--cached)
 			cached="$1"
 			;;
+		-n|--summary-limit)
+			if summary_limit=$(($2 + 0)) 2>/dev/null && test "$summary_limit" = "$2"
+			then
+				:
+			else
+				usage
+			fi
+			shift
+			;;
 		--)
 			shift
 			break
@@ -350,6 +363,8 @@ cmd_summary() {
 		shift
 	done
 
+	test $summary_limit = 0 && return
+
 	if rev=$(git rev-parse --verify "$1^0" 2>/dev/null)
 	then
 		head=$rev
@@ -442,8 +457,52 @@ cmd_summary() {
 			# Don't give error msg for modification whose dst is not submodule, i.e. deleted or changed to blob
 			test $mod_dst = 160000 && echo "$errmsg"
 		else
-			test -n "$left" && echo "$left"
-			test -n "$right" && echo "$right"
+			lc0=0
+			rc0=0
+			test -n "$left" && lc0=$(echo "$left" | wc -l)
+			test -n "$right" && rc0=$(echo "$right" | wc -l)
+
+			if test $summary_limit -lt 0
+			then
+				lc=$lc0
+				rc=$rc0
+			elif test $lc0 -lt $summary_limit
+			then
+				lc=$lc0
+				rc=$(($summary_limit-$lc))
+			else
+				lc=$summary_limit
+				rc=1
+			fi
+
+			if test $rc -gt $rc0
+			then
+				rc=$rc0
+			fi
+
+			if test -n "$left"
+			then
+				skip=$(($lc0-$lc))
+				echo "$left" | head -$(($lc-1))
+				case $skip in
+					0) : ;;
+					1) echo "  <..." ;;
+					*) echo "  <... ($skip more)" ;;
+				esac
+				echo "$left" | tail -1
+			fi
+
+			if test -n "$right"
+			then
+				skip=$(($rc0-$rc))
+				echo "$right" | head -$(($rc-1))
+				case $skip in
+					0) : ;;
+					1) echo "  <..." ;;
+					*) echo "  <... ($skip more)" ;;
+				esac
+				echo "$right" | tail -1
+			fi
 		fi
 		echo
 	done | sed -e 's/^/# /'
-- 
1.5.4.3.347.g5314c

Re: [PATCH v3 3/4] git-submodule: New subcommand 'summary' (3) - limit summary size

[Junio C Hamano]

Ping Yin <pkufranky@gmail.com> writes:

> This patch teaches git-submodule an option '--summary-limit|-n <number>'
> to limit number of commits in total for the summary. Number 0 will disable
> summary and minus number means unlimted (the default).

I really doubt showing the bottom one specially makes sense.

Why not just read from

	git log '--pretty=%m %h %s' --left-right --topo-order A...B

and show N top commits from each?

I've already said that I do not think applying the same limit to
new/deleted/modified cases makes sense, so commenting on this
part might be a moot point, though.

-- >8 --

#!/bin/sh

limit=10
A=cc/run-command
B=jc/test

lf='
'
git log --pretty=format:%m\ %h\ %s --left-right $A...$B |
(
	left=0 right=0 l= r= llast= rlast=
	ilimit=$(( $limit - 1 ))
	while read leftright commit name
	do
		it="$leftright$commit $name"
		case "$leftright" in
		'<')
			if test $left -eq $ilimit
			then
				llast=$it
			elif test $left -le $ilimit
			then
				l="$l$it$lf"
			fi
			left=$(( $left + 1 ))
			;;
		'>')
			if test $right -eq $ilimit
			then
				rlast=$it
			elif test $right -le $ilimit
			then
				r="$r$it$lf"
			fi
			right=$(( $right + 1 ))
			;;
		esac
	done

	printf %s "$l"
	if test $left -eq $limit
	then
		echo "$llast"
	elif test $left -gt $limit
	then
		echo "< ("$(( $left - $limit ))" more...)"
	fi
	printf %s "$r"
	if test $right -eq $limit
	then
		echo "$rlast"
	elif test $right -gt $limit
	then
		echo "> ("$(( $right - $limit ))" more...)"
	fi
)

Re: [PATCH v3 3/4] git-submodule: New subcommand 'summary' (3) - limit summary size

[Ping Yin]

On Thu, Mar 6, 2008 at 8:24 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Ping Yin <pkufranky@gmail.com> writes:
>
>  > This patch teaches git-submodule an option '--summary-limit|-n <number>'
>  > to limit number of commits in total for the summary. Number 0 will disable
>  > summary and minus number means unlimted (the default).
>
>  I really doubt showing the bottom one specially makes sense.
>
>  Why not just read from
>
>         git log '--pretty=%m %h %s' --left-right --topo-order A...B
>
>  and show N top commits from each?
I don't have strong point about this. This one sounds fine to me and
will make my patch much simpler.

>
>  I've already said that I do not think applying the same limit to
>  new/deleted/modified cases makes sense, so commenting on this
>  part might be a moot point, though.
>

Howabout a new option to limit the added/deleted case which default to 1 or 2?



-- 
Ping Yin

Re: [PATCH v3 3/4] git-submodule: New subcommand 'summary' (3) - limit summary size

[Ping Yin]

On Thu, Mar 6, 2008 at 10:24 AM, Ping Yin <pkufranky@gmail.com> wrote:
> On Thu, Mar 6, 2008 at 8:24 AM, Junio C Hamano <gitster@pobox.com> wrote:
>  > Ping Yin <pkufranky@gmail.com> writes:
>  >
>  >  > This patch teaches git-submodule an option '--summary-limit|-n <number>'
>  >  > to limit number of commits in total for the summary. Number 0 will disable
>  >  > summary and minus number means unlimted (the default).
>  >
>  >  I really doubt showing the bottom one specially makes sense.
>  >
>  >  Why not just read from
>  >
>  >         git log '--pretty=%m %h %s' --left-right --topo-order A...B
>  >
>  >  and show N top commits from each?

I doubt '%h' is useful and it may result in overlong message lines.
Is '--topo-order' expensive when only show top N commits?
I prefer to use

    git log --pretty='format:%m %s' --left-right --first-parent A...B

for modificated modules, and

   git log -1 --pretty='format:> %s' $sha1_dst
   git log -1 --pretty='format:< %s' $sha1_src

for added ( or blob -> submodule typechange) and deleted
( or submodule -> blob typechange) modules separately.




-- 
Ping Yin

[PATCH v3 4/4] git-submodule: New subcommand 'summary' (4) - Update the document

[Ping Yin]

Signed-off-by: Ping Yin <pkufranky@gmail.com>
---
 Documentation/git-submodule.txt |   24 +++++++++++++++++++++---
 1 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index e818e6e..598e116 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -12,6 +12,7 @@ SYNOPSIS
 'git-submodule' [--quiet] add [-b branch] [--] <repository> [<path>]
 'git-submodule' [--quiet] status [--cached] [--] [<path>...]
 'git-submodule' [--quiet] [init|update] [--] [<path>...]
+'git-submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
 
 
 COMMANDS
@@ -46,6 +47,13 @@ update::
 	checkout the commit specified in the index of the containing repository.
 	This will make the submodules HEAD be detached.
 
+summary::
+	Show commit summary between given commit (default to HEAD) and
+	working tree/index. For a submodule in question, a series of commits
+	will be shown as the path from the src commit to the dst commit,
+	where the src commit is from the given super project commit, and the
+	dst commit is from the index or working tree (switched by --cached).
+
 
 OPTIONS
 -------
@@ -56,9 +64,19 @@ OPTIONS
 	Branch of repository to add as submodule.
 
 --cached::
-	Display the SHA-1 stored in the index, not the SHA-1 of the currently
-	checked out submodule commit. This option is only valid for the
-	status command.
+	This option is only valid for commands status and summary.
+	When combined with status, display the SHA-1 stored in the index,
+	not the SHA-1 of the currently checked out submodule commit. When
+	combined with summary, switch dst comparison side from working
+	tree to index.
+
+-n, --summary-limit::
+	This option is only valid for the summary command.
+	Limit the summary size (number of commits shown in total).
+	Number 0 will disable summary and minus number means unlimted
+	(the default). For beauty and clarification, the fork-point commits
+	will always be shown. So actual summary size may be greater than
+	the given limit.
 
 <path>::
 	Path to submodule(s). When specified this will restrict the command
-- 
1.5.4.3.347.g5314c