v3, 4 partsgit-submodule: New subcommand 'summary' (3) - limit summary size

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(-)

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(-)

Ping Yin <pkufranky@gmail.com> writes:

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?

On Thu, Mar 6, 2008 at 7:57 AM, Junio C Hamano <gitster@pobox.com> wrote:

Good point to show 'log --left-right --topo-order' is better

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

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" <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.

On Thu, Mar 6, 2008 at 12:10 PM, Junio C Hamano <gitster@pobox.com> wrote:

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" <pkufranky@gmail.com> writes:

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."

On Thu, Mar 6, 2008 at 6:42 PM, Junio C Hamano <gitster@pobox.com> wrote:

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.

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(-)

Ping Yin <pkufranky@gmail.com> writes:

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
)

On Thu, Mar 6, 2008 at 8:24 AM, Junio C Hamano <gitster@pobox.com> wrote:

I don't have strong point about this. This one sounds fine to me and will make my patch much simpler.

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

On Thu, Mar 6, 2008 at 10:24 AM, Ping Yin <pkufranky@gmail.com> wrote:

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.

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