A Makefile help target

The longer I’m around in this industry, the more I rely on Makefiles to remember all the steps I need to take. If something else doesn’t put the steps in order, I’m not likely to remember everything myself. This website even has a /Makefile (it is all in a public GitHub repo, so have at it), and it has a feature that I’ve come to love.

François Zaninotto wrote about Self-documented Makefile. He didn’t really document the Makefile so much as give it a target summary like you’d get from rake:

$ make help
error               show the error from the last build
help                show a list of targets
publish             Remake stuff and send it to GitHub
rebuild             tell GitHub to rebuild the site
setup               setup the tools (try to install what you need)
show_vars           show some variables, useful for debugging
spell               spellcheck the markdown files in _posts/
status              show the GitHub Pages build status
tag                 create the tag files

Usually I know I have a target for something but I forget the name. Although I usually have the Makefile open, I have an easier time with make help. That is, when I remember to use it.

It’s an easy task. Grep the Makefile for targets (which is very easy because the targets start at the first column) and check if there’s a ## comment after it. Sort what you find and format it.

######################################################################
# https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
.PHONY: help ## Show all the Makefile targets with descriptions
help: ## show a list of targets
	@grep -E '^[a-zA-Z][/a-zA-Z0-9_.-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'