v3, 7 partsDetailed test coverage reports for Git

diff --git a/.gitignore b/.gitignore
index 14e2b6b..57f79ef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -181,6 +181,10 @@
 *.[aos]
 *.py[co]
 .depend/
+*.gcda
+*.gcno
+*.gcov
+/coverage-untested-functions
 *+
 /config.mak
 /autom4te.cache

diff --git a/Makefile b/Makefile
index bc3c570..b791ad5 100644
--- a/Makefile
+++ b/Makefile
@@ -1485,6 +1485,7 @@ ifndef V
 	QUIET_BUILT_IN = @echo '   ' BUILTIN $@;
 	QUIET_GEN      = @echo '   ' GEN $@;
 	QUIET_LNCP     = @echo '   ' LN/CP $@;
+	QUIET_GCOV     = @echo '   ' GCOV $@;
 	QUIET_SUBDIR0  = +@subdir=
 	QUIET_SUBDIR1  = ;$(NO_SUBDIR) echo '   ' SUBDIR $$subdir; \
 			 $(MAKE) $(PRINT_DIR) -C $$subdir
@@ -2280,11 +2281,16 @@ coverage:
 	$(MAKE) coverage-build
 	$(MAKE) coverage-report
 
+object_dirs := $(sort $(dir $(OBJECTS)))
 coverage-clean:
-	rm -f *.gcda *.gcno
+	$(RM) $(addsuffix *.gcov,$(object_dirs))
+	$(RM) $(addsuffix *.gcda,$(object_dirs))
+	$(RM) $(addsuffix *.gcno,$(object_dirs))
+	$(RM) coverage-untested-functions
 
 COVERAGE_CFLAGS = $(CFLAGS) -O0 -ftest-coverage -fprofile-arcs
 COVERAGE_LDFLAGS = $(CFLAGS)  -O0 -lgcov
+GCOVFLAGS = --preserve-paths --branch-probabilities --all-blocks
 
 coverage-build: coverage-clean
 	$(MAKE) CFLAGS="$(COVERAGE_CFLAGS)" LDFLAGS="$(COVERAGE_LDFLAGS)" all
@@ -2292,7 +2298,9 @@ coverage-build: coverage-clean
 		-j1 test
 
 coverage-report:
-	gcov -b *.c
+	$(QUIET_GCOV)for dir in $(object_dirs); do \
+		gcov $(GCOVFLAGS) --object-directory=$$dir $$dir*.c || exit; \
+	done
 	grep '^function.*called 0 ' *.c.gcov \
 		| sed -e 's/\([^:]*\)\.gcov: *function \([^ ]*\) called.*/\1: \2/' \
-		| tee coverage-untested-functions
+		> coverage-untested-functions

diff --git a/Makefile b/Makefile
index b791ad5..40453f1 100644
--- a/Makefile
+++ b/Makefile
@@ -2301,6 +2301,8 @@ coverage-report:
 	$(QUIET_GCOV)for dir in $(object_dirs); do \
 		gcov $(GCOVFLAGS) --object-directory=$$dir $$dir*.c || exit; \
 	done
+
+coverage-untested-functions: coverage-report
 	grep '^function.*called 0 ' *.c.gcov \
 		| sed -e 's/\([^:]*\)\.gcov: *function \([^ ]*\) called.*/\1: \2/' \
 		> coverage-untested-functions

.gitignore, Makefile

diff --git a/.gitignore b/.gitignore
index 57f79ef..d8bd555 100644
--- a/.gitignore
+++ b/.gitignore
@@ -185,6 +185,7 @@
 *.gcno
 *.gcov
 /coverage-untested-functions
+/cover_db/
 *+
 /config.mak
 /autom4te.cache
diff --git a/Makefile b/Makefile
index 40453f1..1d721ef 100644
--- a/Makefile
+++ b/Makefile
@@ -2287,6 +2287,7 @@ coverage-clean:
 	$(RM) $(addsuffix *.gcda,$(object_dirs))
 	$(RM) $(addsuffix *.gcno,$(object_dirs))
 	$(RM) coverage-untested-functions
+	$(RM) -r cover_db/
 
 COVERAGE_CFLAGS = $(CFLAGS) -O0 -ftest-coverage -fprofile-arcs
 COVERAGE_LDFLAGS = $(CFLAGS)  -O0 -lgcov
@@ -2306,3 +2307,6 @@ coverage-untested-functions: coverage-report
 	grep '^function.*called 0 ' *.c.gcov \
 		| sed -e 's/\([^:]*\)\.gcov: *function \([^ ]*\) called.*/\1: \2/' \
 		> coverage-untested-functions
+
+cover_db: coverage-report
+	gcov2perl -db cover_db *.gcov

.gitignore, Makefile

diff --git a/.gitignore b/.gitignore
index d8bd555..0a30a7e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -186,6 +186,7 @@
 *.gcov
 /coverage-untested-functions
 /cover_db/
+/cover_db_html/
 *+
 /config.mak
 /autom4te.cache
diff --git a/Makefile b/Makefile
index 1d721ef..fdfa4fe 100644
--- a/Makefile
+++ b/Makefile
@@ -2288,6 +2288,7 @@ coverage-clean:
 	$(RM) $(addsuffix *.gcno,$(object_dirs))
 	$(RM) coverage-untested-functions
 	$(RM) -r cover_db/
+	$(RM) -r cover_db_html/
 
 COVERAGE_CFLAGS = $(CFLAGS) -O0 -ftest-coverage -fprofile-arcs
 COVERAGE_LDFLAGS = $(CFLAGS)  -O0 -lgcov
@@ -2310,3 +2311,6 @@ coverage-untested-functions: coverage-report
 
 cover_db: coverage-report
 	gcov2perl -db cover_db *.gcov
+
+cover_db_html: cover_db
+	cover -report html -outputdir cover_db_html cover_db

diff --git a/t/README b/t/README
index 0d1183c..15d4b52 100644
--- a/t/README
+++ b/t/README
@@ -268,6 +268,9 @@ Do:
 	git push gh &&
 	test ...
 
+ - Check the test coverage for your tests. See the "Test coverage"
+   below.
+
 Don't:
 
  - exit() within a <script> part.
@@ -508,3 +511,42 @@ the purpose of t0000-basic.sh, which is to isolate that level of
 validation in one place.  Your test also ends up needing
 updating when such a change to the internal happens, so do _not_
 do it and leave the low level of validation to t0000-basic.sh.
+
+Test coverage
+-------------
+
+You can use the coverage tests to find code paths that are not being
+used or properly exercised yet.
+
+To do that, run the coverage target at the top-level (not in the t/
+directory):
+
+    make coverage
+
+That'll compile Git with GCC's coverage arguments, and generate a test
+report with gcov after the tests finish. Running the coverage tests
+can take a while, since running the tests in parallel is incompatible
+with GCC's coverage mode.
+
+After the tests have run you can generate a list of untested
+functions:
+
+    make coverage-untested-functions
+
+You can also generate a detailed per-file HTML report using the
+Devel::Cover module. To install it do:
+
+   # On Debian or Ubuntu:
+   sudo aptitude install libdevel-cover-perl
+
+   # From the CPAN with cpanminus
+   curl -L http://cpanmin.us | perl - --sudo --self-upgrade
+   cpanm --sudo Devel::Cover
+
+Then, at the top-level:
+
+    make cover_db_html
+
+That'll generate a detailed cover report in the "cover_db_html"
+directory, which you can then copy to a webserver, or inspect locally
+in a browser.

diff --git a/t/README b/t/README
index 15d4b52..4fe8d50 100644
--- a/t/README
+++ b/t/README
@@ -271,6 +271,15 @@ Do:
  - Check the test coverage for your tests. See the "Test coverage"
    below.
 
+   Don't blindly follow test coverage metrics, they're a good way to
+   spot if you've missed something. If a new function you added
+   doesn't have any coverage you're probably doing something wrong,
+   but having 100% coverage doesn't necessarily mean that you tested
+   everything.
+
+   Tests that are likely to smoke out future regressions are better
+   than tests that just inflate the coverage metrics.
+
 Don't:
 
  - exit() within a <script> part.

diff --git a/Makefile b/Makefile
index fdfa4fe..81cb5ac 100644
--- a/Makefile
+++ b/Makefile
@@ -308,6 +308,7 @@ TCL_PATH = tclsh
 TCLTK_PATH = wish
 PTHREAD_LIBS = -lpthread
 PTHREAD_CFLAGS =
+GCOV = gcov
 
 export TCL_PATH TCLTK_PATH
 
@@ -2301,7 +2302,7 @@ coverage-build: coverage-clean
 
 coverage-report:
 	$(QUIET_GCOV)for dir in $(object_dirs); do \
-		gcov $(GCOVFLAGS) --object-directory=$$dir $$dir*.c || exit; \
+		$(GCOV) $(GCOVFLAGS) --object-directory=$$dir $$dir*.c || exit; \
 	done
 
 coverage-untested-functions: coverage-report