Add a help target to a Makefile that will allow all targets to be self documenting

Makefile

# Add the following 'help' target to your Makefile
# And add help text after each target name starting with '\#\#'
 
help:           ## Show this help.
	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
 
# Everything below is an example
 
target00:       ## This message will show up when typing 'make help'
	@echo does nothing
 
target01:       ## This message will also show up when typing 'make help'
	@echo does something
 
# Remember that targets can have multiple entries (if your target specifications are very long, etc.)
target02:       ## This message will show up too!!!
target02: target00 target01
	@echo does even more

Output will be:

help: Show this help.
target00: This message will show up when typing 'make help'
target01: This message will also show up when typing 'make help'
target02: This message will show up too!!!

This is great! Thanks for sharing it.

Here's a modified help command I've put together so the messages are pushed out to the same point:

help: ## This help dialog.
    @IFS=$$'\n' ; \
    help_lines=(`fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//'`); \
    for help_line in $${help_lines[@]}; do \
        IFS=$$'#' ; \
        help_split=($$help_line) ; \
        help_command=`echo $${help_split[0]} | sed -e 's/^ *//' -e 's/ *$$//'` ; \
        help_info=`echo $${help_split[2]} | sed -e 's/^ *//' -e 's/ *$$//'` ; \
        printf "%-30s %s\n" $$help_command $$help_info ; \
    done

# Everything below is an example

target00: ## This message will show up when typing 'make help'
    @echo does nothing

target01: ## This message will also show up when typing 'make help'
    @echo does something

# Remember that targets can have multiple entries (if your target specifications are very long, etc.)
target02:  ## This message will show up too!!!
target02: target00 target01
    @echo does even more

will respond with:

help:                          This help dialog.
target00:                      This message will show up when typing 'make help'
target01:                      This message will also show up when typing 'make help'
target02:                      This message will show up too!!!

Thanks to the both of you for providing this.

I've made a version using only awk (tested on OS X, but possible works on gawk too). I also moved the help message just before the task - so you don't need to declare the target multiple times:

https://gist.github.com/rcmachado/af3db315e31383502660

Very nice idea. I modified it with a small Perl script that support categories:

 # Add the following 'help' target to your Makefile
 # And add help text after each target name starting with '\#\#'
 # A category can be added with @category

 HELP_FUN = \
         %help; \
         while(<>) { push @{$$help{$$2 // 'options'}}, [$$1, $$3] if /^(\w+)\s*:.*\#\#(?:@(\w+))?\s(.*)$$/ }; \
         print "usage: make [target]\n\n"; \
     for (keys %help) { \
         print "$$_:\n"; $$sep = " " x (20 - length $$_->[0]); \
         print "  $$_->[0]$$sep$$_->[1]\n" for @{$$help{$$_}}; \
         print "\n"; }     

 help:           ##@miscellaneous Show this help.
     @perl -e '$(HELP_FUN)' $(MAKEFILE_LIST)

 # Everything below is an example

 target00:       ##@foo This message will show up when typing 'make help'
     @echo does nothing

 target01:       ##@foo This message will also show up when typing 'make help'
     @echo does something

 # Remember that targets can have multiple entries (if your target specifications are very long, etc.)
 target02:       ## This message will show up too!!!
 target02: target00 target01
     @echo does even more

The output is this:

 $ make help
 usage: make [target]

 options:
   target02                    This message will show up too!!!

 foo:
   target00                    This message will show up when typing 'make help'
   target01                    This message will also show up when typing 'make help'

 miscellaneous:
   help                    Show this help.

This is awesome! I wanted ANSI colors so ...

help: ## This help dialog.
    @IFS=$$'\n' ; \
    help_lines=(`fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##/:/'`); \
    printf "%-30s %s\n" "target" "help" ; \
    printf "%-30s %s\n" "------" "----" ; \
    for help_line in $${help_lines[@]}; do \
        IFS=$$':' ; \
        help_split=($$help_line) ; \
        help_command=`echo $${help_split[0]} | sed -e 's/^ *//' -e 's/ *$$//'` ; \
        help_info=`echo $${help_split[2]} | sed -e 's/^ *//' -e 's/ *$$//'` ; \
        printf '\033[36m'; \
        printf "%-30s %s" $$help_command ; \
        printf '\033[0m'; \
        printf "%s\n" $$help_info; \
    done

target: ## Does absolutely nothing!
    exit 0

This is great stuff. Can you declare a licence, so I can use it in good conscience?

@nowox I know this gist is quite old but I liked your solution. I just had to make a small modification and wanted to share

• Modified the regex to match rules that have special chars in them
• Sort help hash before generating messages for consistent output
• Use printf with a fixed width column for consistent output. (There where alignment issues in your initial implementation)

HELP_FUNC = \
    %help; \
    while(<>) { \
        if(/^([a-z0-9_-]+):.*\#\#(?:@(\w+))?\s(.*)$$/) { \
            push(@{$$help{$$2}}, [$$1, $$3]); \
        } \
    }; \
    print "usage: make [target]\n\n"; \
    for ( sort keys %help ) { \
        print "$$_:\n"; \
        printf("  %-20s %s\n", $$_->[0], $$_->[1]) for @{$$help{$$_}}; \
        print "\n"; \
    }

Here's my take:

• Colored target names
• Used column to have reasonable spacing between the target and help message
• Help comments can be on the same line as target dependencies

# Needed SHELL since I'm using zsh
SHELL := /bin/bash
.PHONY: help

# Add the following 'help' target to your Makefile
# And add help text after each target name starting with '\#\#'

help: ## This help message
    @echo -e "$$(grep -hE '^\S+:.*##' $(MAKEFILE_LIST) | sed -e 's/:.*##\s*/:/' -e 's/^\(.\+\):\(.*\)/\\x1b[36m\1\\x1b[m:\2/' | column -c2 -t -s :)"

# Everything below is an example

target00:       ## This message will show up when typing 'make help'
    @echo does nothing

target01:       ## This message will also show up when typing 'make help'
    @echo does something

# Remember that targets can have multiple entries (if your target specifications are very long, etc.)
target02:       ## This message will show up too!!!
target02: target00 target01
    @echo does even more

If anyone is interested, I wrote a package for that: make-help

The following Makefile:

# generate all assets
build: scripts styles

# show some help
help:
    echo
    echo '  Usage:'
    echo '    make <target>'
    echo
    echo '  Targets:'
    make-help -p 4 "$(lastword $(MAKEFILE_LIST))"
    echo

# generete scripts
scripts:
    ...

# generete styles
styles:
    ...

Will output this when make help is called:

  Usage:
    make <target>

  Targets:
    build    generate all assets
    help     show some help
    scripts  generete scripts
    styles   generete styles

@nowox version with colors and repair targets with - and separator length:

#COLORS
GREEN  := $(shell tput -Txterm setaf 2)
WHITE  := $(shell tput -Txterm setaf 7)
YELLOW := $(shell tput -Txterm setaf 3)
RESET  := $(shell tput -Txterm sgr0)

# Add the following 'help' target to your Makefile
# And add help text after each target name starting with '\#\#'
# A category can be added with @category
HELP_FUN = \
    %help; \
    while(<>) { push @{$$help{$$2 // 'options'}}, [$$1, $$3] if /^([a-zA-Z\-]+)\s*:.*\#\#(?:@([a-zA-Z\-]+))?\s(.*)$$/ }; \
    print "usage: make [target]\n\n"; \
    for (sort keys %help) { \
    print "${WHITE}$$_:${RESET}\n"; \
    for (@{$$help{$$_}}) { \
    $$sep = " " x (32 - length $$_->[0]); \
    print "  ${YELLOW}$$_->[0]${RESET}$$sep${GREEN}$$_->[1]${RESET}\n"; \
    }; \
    print "\n"; }

help: ##@other Show this help.
    @perl -e '$(HELP_FUN)' $(MAKEFILE_LIST)

Any way to make this support targets created with templates?
https://www.gnu.org/software/make/manual/html_node/Eval-Function.html

@caylorme you need to modify fragment [a-zA-Z\-] to like this [a-zA-Z\-\$\(\)]

I'm starting to use the following:

.PHONY: help
help: ## Show this help message.
    echo 'usage: make [target] ...'
    echo
    echo 'targets:'
    egrep '^(.+)\:\ ##\ (.+)' ${MAKEFILE_LIST} | column -t -c 2 -s ':#'

Would somebody help on how to make the entire help that is in multiple lines show up aligned with first line of help associated with the target?

Example: For below make file content

target00: ## This message will show up when typing 'make help'
    @echo does nothing

target01: ## This message will also show up when typing 'make help'
    @echo does something

# Remember that targets can have multiple entries (if your target specifications are very long, etc.)
target02:  ## This message will show up too!!!
## This help message is way too long so it is in multiple line
target02: target00 target01
    @echo does even more

Desired output:
help:                     This help dialog.
target00:              This message will show up when typing 'make help'
target01:              This message will also show up when typing 'make help'
target02:              This message will show up too!!!
                              This help message is way too long so it is in multiple line

@nowox (20 - length $$_->[0]) always return 20 for me

reference above and others, updated to Colorful and usable syntax:

# COLORS
GREEN  := $(shell tput -Txterm setaf 2)
YELLOW := $(shell tput -Txterm setaf 3)
WHITE  := $(shell tput -Txterm setaf 7)
RESET  := $(shell tput -Txterm sgr0)


TARGET_MAX_CHAR_NUM=20
## Show help
help:
	@echo ''
	@echo 'Usage:'
	@echo '  ${YELLOW}make${RESET} ${GREEN}<target>${RESET}'
	@echo ''
	@echo 'Targets:'
	@awk '/^[a-zA-Z\-\_0-9]+:/ { \
		helpMessage = match(lastLine, /^## (.*)/); \
		if (helpMessage) { \
			helpCommand = substr($$1, 0, index($$1, ":")-1); \
			helpMessage = substr(lastLine, RSTART + 3, RLENGTH); \
			printf "  ${YELLOW}%-$(TARGET_MAX_CHAR_NUM)s${RESET} ${GREEN}%s${RESET}\n", helpCommand, helpMessage; \
		} \
	} \
	{ lastLine = $$0 }' $(MAKEFILE_LIST)

then above target use ## target description, example:

## Generate Mobi file
mobi: clean_mobi create_foler_mobi
	gitbook mobi $(CURRENT_DIR_NOSLASH) $(MOBI_FULLNAME)

## Generate all files: website/pdf/epub/mobi
all: website pdf epub mobi

will generate colorful help info:

for latest makefile pls refer my: Makefile

Thanks for these tips on make help

Here is my Makefile for C/C++ development.

Hi @muhmi, I try your solution in Ubuntu but I get this error 😞

'/bin/sh: 2: Syntax error: "(" unexpected
Makefile:144: fallo en las instrucciones para el objetivo 'help'
make: *** [help] Error 2'

you know what could be the reason?

Wow, these are great 🎉 Thanks for sharing!

I did something similar in ludicrous-makefiles (here and here), which handles multiple lines of help text for each target and also generate a prologue from any comments not directly associated with a target (I used #> as the marker instead of ##). No colors, but that's a nice touch so I'll probably add them!

@crifan I particularly like the readability and conciseness of your awk! For some reason it truncates targets by 1 character for me on ubuntu:18.04 (using mawk 1.3.3), but this change seems to help ...

19c19
< 			helpCommand = substr($$1, 0, index($$1, ":")-1); \
---
> 			helpCommand = $$1; sub(/:$$/, "", helpCommand); \

no perl, grouping per @label_with_some_description
(sorting only on @Label, skipping sorting the targets)

default: | help-prefix help-targets

help-prefix:
	@echo Whatever help info you want here, eg
	@echo '  make <target>'
	@echo '  make <target> <VAR>=<value>'
	@echo ''

## @info help
test:

## @abc help
test2:

## @info help2
a:

# --- helper

HELP_TARGET_MAX_CHAR_NUM = 20

help-targets:
	@awk '/^[a-zA-Z\-\_0-9]+:/ \
		{ \
			helpMessage = match(lastLine, /^## (.*)/); \
			if (helpMessage) { \
				helpCommand = substr($$1, 0, index($$1, ":")-1); \
				helpMessage = substr(lastLine, RSTART + 3, RLENGTH); \
				helpGroup = match(helpMessage, /^@([^ ]*)/); \
				if (helpGroup) { \
					helpGroup = substr(helpMessage, RSTART + 1, index(helpMessage, " ")-2); \
					helpMessage = substr(helpMessage, index(helpMessage, " ")+1); \
				} \
				printf "%s|  %-$(HELP_TARGET_MAX_CHAR_NUM)s %s\n", \
					helpGroup, helpCommand, helpMessage; \
			} \
		} \
		{ lastLine = $$0 }' \
		$(MAKEFILE_LIST) \
	| sort -t'|' -sk1,1 \
	| awk -F '|' ' \
			{ \
			cat = $$1; \
			if (cat != lastCat || lastCat == "") { \
				if ( cat == "0" ) { \
					print "Targets:" \
				} else { \
					gsub("_", " ", cat); \
					printf "Targets %s:\n", cat; \
				} \
			} \
			print $$2 \
		} \
		{ lastCat = $$1 }'
	

I'm now using the following based on the post of @hans-d. It doesn't have the grouping feature, but does have multi-line doc strings.

Features

• only awk (works cross platform)
• multi-line doc strings
• doc strings aligned to right
• section delimiters

.DEFAULT_GOAL := help

## -- Section Delimiter --

## This help message
## Which can also be multiline
.PHONY: help
help:
	@printf "Usage\n";

	@awk '{ \
			if ($$0 ~ /^.PHONY: [a-zA-Z\-\_0-9]+$$/) { \
				helpCommand = substr($$0, index($$0, ":") + 2); \
				if (helpMessage) { \
					printf "\033[36m%-20s\033[0m %s\n", \
						helpCommand, helpMessage; \
					helpMessage = ""; \
				} \
			} else if ($$0 ~ /^[a-zA-Z\-\_0-9.]+:/) { \
				helpCommand = substr($$0, 0, index($$0, ":")); \
				if (helpMessage) { \
					printf "\033[36m%-20s\033[0m %s\n", \
						helpCommand, helpMessage; \
					helpMessage = ""; \
				} \
			} else if ($$0 ~ /^##/) { \
				if (helpMessage) { \
					helpMessage = helpMessage"\n                     "substr($$0, 3); \
				} else { \
					helpMessage = substr($$0, 3); \
				} \
			} else { \
				if (helpMessage) { \
					print "\n                     "helpMessage"\n" \
				} \
				helpMessage = ""; \
			} \
		}' \
		$(MAKEFILE_LIST)

## -- QA Task Runners --

## Run linter
.PHONY: lint
lint:
	exit 0


## Run unit and integration tests
.PHONY: test
test:
	exit 0

Output

$ make help

                   -- Section Delimiter --

help               This help message
                   Which can also be multiline

                   -- QA Task Runners --

lint               Run linter
test               Run unit and integration tests

I'm using version from here, it works great but I would like to support also templates. I tried to modify [a-zA-Z_-] but I stuck :/

Makefile

.DEFAULT_GOAL:=help

##@ Build
.PHONY: build

build: ## build something
	@echo "Bulding..."

##@ Clean
.PHONY: clean

cache: ## clean something
	@echo "Cleaning..."

define template =
##@ Section $(2)

.PHONY: $(1)-foo
$(1)-foo: ## Foo $(2)
	@echo "Doing $(2)-foo..."

.PHONY: $(1)-bar
$(1)-bar: ## Bar $(2)
	@echo "Doing $(2)-bar..."
endef

$(eval $(call template,a,Apple))
$(eval $(call template,l,Linux))

.PHONY: help
help:
	@awk 'BEGIN {FS = ":.*##"; printf "Usage: make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

Current output

Usage: make <target>

Build
  build       build something

Clean
  cache       clean something

Section $(2)

Needed output

Usage: make <target>

Build
  build       build something

Clean
  cache       clean something

Section Apple
  a-foo       Foo Apple
  a-bar       Bar Apple

Section Linux
  l-foo       Foo Linux
  l-bar       Bar Linux

Is there someone who can help?
Thank you! :)

@o5, simple regex for makefile eval is not enough, you must use recurrent makefile with --print-data-base to extract evaluated recipes.
See here: https://stackoverflow.com/questions/4219255/how-do-you-get-the-list-of-targets-in-a-makefile/26339924#26339924

This gist totally "triggered" me and kickstarted all my gizmos quite some time back - thank you so much for it! Also thanks to @lordnynex and @HarasimowiczKamil for your comments. Sorry it took me some years to comment here but better later than never ;-)

I took the idea a bit further and puzzled together some other bits and pieces (e.g. including variables) - have a look at https://github.com/25th-floor/docker-make-stub ... Feedback is highly appreciated!

First go for a single line version.. fully awk.. place this at the end of your make file. it will print all recipes.

## print help
help:
	@printf "\nusage : make <commands> \n\nthe following commands are available : \n\n"
	@cat Makefile | awk '1;/help:/{exit}' | awk '/##/ { print; getline; print; }' | awk '{ getline x; print x; }1' | awk '{ key=$$0; getline; print key "\t\t\t\t " $$0;}'
	@printf "\n"

to yield

usage : make <commands>

the following commands are available :

help:				 ## print help

some issues in removing the ":" and "##" as well as trying to get colours for the menu item. otherwise its quite usable. this way is much faster as it does not loop and try to modify each line.

You don't need this whole pipeline. One sed is enough:

help:           ##- Show this help.
	@sed -e '/#\{2\}-/!d; s/\\$$//; s/:[^#\t]*/:/; s/#\{2\}- *//' $(MAKEFILE_LIST)

Comments on this alternative:

• sed can accept multiple commands delimited with ;.
• sed can skip lines not matching a pattern with the /pattern/!d command. This saves us from having to use grep.
• Lines consisting entirely of # are often used as horizontal rules in Makefiles. Using ##- as the delimiter prevents them from being printed.
• s/:[^#\t]*/:/ is used to eliminate the need to add an additional entry for the target help message.
• /#\{2\}-/!d is used instead of the equivalent /##-/!d so that the line containing the sed command doesn't match.

Golfing here. One awk might be enough

.PHONY: help help_target-funky+names.0k and_with_2_targets_and_spaces_like_bison phony targets
help: ## Show this help.
help: phony targets ## Show this help here too.
        @awk '/^[a-zA-Z0-9\-_+. ]*:[a-zA-Z0-9\-_+. ]*#{2}/ { print; }' $(MAKEFILE_LIST)
help_target-funky+names.0k and_with_2_targets_and_spaces_like_bison: ## Show this help too.

It works nicely. You might want to make a minor improvement:

@fgrep -h "##" $(MAKEFILE_LIST) | sed -e 's/\(\:.*\#\#\)/\:\ /' | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'

This will print only the targets without their dependencies.

all:  Runs the tests and builds the binary deliverable of the project using cython.
clean:  Cleans all the intermediate files and folders previously generated.
compile-proto:  Compiles the models protocol buffer files and gRPC stubs.
prereqs:  Installs all the prerequisites for this project.
test:  Runs all the available tests for this project.
cythonize:  Builds a binary deliverable using Cython.