From 4fd8b490b4badd13c0ea46408e44dc7b317dc0ed Mon Sep 17 00:00:00 2001
From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Tue, 28 Sep 2010 16:34:31 +0200
Subject: [PATCH] Makefile: implement help target

with automatic help text collection from lines starting with "# Help: " and
preceding a make target.

Suggested-by: Stephen Boyd <bebarino@gmail.com>
Helped-by: Andreas Ericsson <andreas.ericsson@op5.se>
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 Makefile | 43 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index db2efd6caa..497dd92dd2 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,5 @@
 # The default target of this Makefile is...
+# Help: Build: Build the Git suite
 all::
 
 # Define V=1 to have a more verbose compile.
@@ -1952,29 +1953,37 @@ $(XDIFF_LIB): $(XDIFF_OBJS)
 $(VCSSVN_LIB): $(VCSSVN_OBJS)
 	$(QUIET_AR)$(RM) $@ && $(AR) rcs $@ $(VCSSVN_OBJS)
 
+# Help: Build: Build man pages and HTML docs
 doc:
 	$(MAKE) -C Documentation all
 
+# Help: Build: Build man pages
 man:
 	$(MAKE) -C Documentation man
 
+# Help: Build: Build HTML doc
 html:
 	$(MAKE) -C Documentation html
 
+# Help: Build: Build info docs
 info:
 	$(MAKE) -C Documentation info
 
+# Help: Build: Build PDF docs
 pdf:
 	$(MAKE) -C Documentation pdf
 
+# Help: Develop: Generate tags using etags
 TAGS:
 	$(RM) TAGS
 	$(FIND) . -name '*.[hcS]' -print | xargs etags -a
 
+# Help: Develop: Generate tags using ctags
 tags:
 	$(RM) tags
 	$(FIND) . -name '*.[hcS]' -print | xargs ctags -a
 
+# Help: Develop: Generate cscope index
 cscope:
 	$(RM) cscope*
 	$(FIND) . -name '*.[hcS]' -print | xargs cscope -b
@@ -2040,6 +2049,7 @@ export NO_SVN_TESTS
 
 ### Testing rules
 
+# Help: Test: Check the build by running the test suite
 test: all
 	$(MAKE) -C t/ all
 
@@ -2099,6 +2109,7 @@ export gitexec_instdir
 
 install_bindir_programs := $(patsubst %,%$X,$(BINDIR_PROGRAMS_NEED_X)) $(BINDIR_PROGRAMS_NO_X)
 
+# Help: Install: Install the Git suite
 install: all
 	$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(bindir_SQ)'
 	$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(gitexec_instdir_SQ)'
@@ -2155,27 +2166,35 @@ endif
 install-gitweb:
 	$(MAKE) -C gitweb install
 
+# Help: Install: Install man pages
 install-doc:
 	$(MAKE) -C Documentation install
 
+# Help: Install: Install man pages
 install-man:
 	$(MAKE) -C Documentation install-man
 
+# Help: Install: Install HTML docs
 install-html:
 	$(MAKE) -C Documentation install-html
 
+# Help: Install: Install info docs
 install-info:
 	$(MAKE) -C Documentation install-info
 
+# Help: Install: Install PDF docs
 install-pdf:
 	$(MAKE) -C Documentation install-pdf
 
+# Help: Install: Install pregenerated man pages from origin/man
 quick-install-doc:
 	$(MAKE) -C Documentation quick-install
 
+# Help: Install: Install pregenerated man pages from origin/man
 quick-install-man:
 	$(MAKE) -C Documentation quick-install-man
 
+# Help: Install: Install pregenerated HTML pages from origin/html
 quick-install-html:
 	$(MAKE) -C Documentation quick-install-html
 
@@ -2188,6 +2207,7 @@ git.spec: git.spec.in
 	mv $@+ $@
 
 GIT_TARNAME=git-$(GIT_VERSION)
+# Help: Build: Build git-$(GIT_VERSION).tar.gz source
 dist: git.spec git-archive$(X) configure
 	./git-archive --format=tar \
 		--prefix=$(GIT_TARNAME)/ HEAD^{tree} > $(GIT_TARNAME).tar
@@ -2203,6 +2223,7 @@ dist: git.spec git-archive$(X) configure
 	@$(RM) -r $(GIT_TARNAME)
 	gzip -f -9 $(GIT_TARNAME).tar
 
+# Help: Build: Build source and binary RPM packages
 rpm: dist
 	$(RPMBUILD) \
 		--define "_source_filedigest_algorithm md5" \
@@ -2211,6 +2232,8 @@ rpm: dist
 
 htmldocs = git-htmldocs-$(GIT_VERSION)
 manpages = git-manpages-$(GIT_VERSION)
+
+# Help: Build: Build $(manpages).tar.gz and $(htmldocs).tar.gz
 dist-doc:
 	$(RM) -r .doc-tmp-dir
 	mkdir .doc-tmp-dir
@@ -2230,10 +2253,11 @@ dist-doc:
 	$(RM) -r .doc-tmp-dir
 
 ### Cleaning rules
-
+# Help: Clean: Remove generated files and the configure script
 distclean: clean
 	$(RM) configure
 
+# Help: Clean: Remove generated files but keep the configure script
 clean:
 	$(RM) *.o block-sha1/*.o ppc/*.o compat/*.o compat/*/*.o xdiff/*.o vcs-svn/*.o \
 		builtin/*.o $(LIB_FILE) $(XDIFF_LIB) $(VCSSVN_LIB)
@@ -2268,7 +2292,7 @@ endif
 .PHONY: FORCE TAGS tags cscope
 
 ### Check documentation
-#
+# Help: Test: Check documentation coverage
 check-docs::
 	@(for v in $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git gitk; \
 	do \
@@ -2335,6 +2359,7 @@ check-builtins::
 #
 .PHONY: coverage coverage-clean coverage-build coverage-report
 
+# Help: Test: Check test coverage
 coverage:
 	$(MAKE) coverage-build
 	$(MAKE) coverage-report
@@ -2370,5 +2395,19 @@ coverage-untested-functions: coverage-report
 cover_db: coverage-report
 	gcov2perl -db cover_db *.gcov
 
+# Help: Test: Check test coverage and create HTML report
 cover_db_html: cover_db
 	cover -report html -outputdir cover_db_html cover_db
+
+# Help: Help: Show help for main make targets
+help:
+	@awk '/^# Help:/ { l=substr($$0,8); \
+		getline; \
+		j=index(l,":"); \
+		print substr(l,1,j-1), substr($$0,1,index($$0,":")), substr(l,j+2); \
+		}' <Makefile | sort | while read category target text; \
+	do \
+		test "$$category" = "$$currcat" || printf "$$category targets:\n"; \
+		currcat="$$category"; \
+		printf "    %-20s%s\n" "$$target" "$$text"; \
+	done
-- 
2.11.4.GIT