Executable READMEs View article history Edit article

Published: , Updated:
Talks about: <a class="post-tag post-tag-make" href="/tags/make">make</a>, <a class="post-tag post-tag-makefile" href="/tags/makefile">Makefile</a>, <a class="post-tag post-tag-readme" href="/tags/readme">README</a>, and <a class="post-tag post-tag-teamwork" href="/tags/teamwork">teamwork</a>

README file typically contain information about the project itself, for example how it can be installed/used/build. Most of the time these files contains command line instructions that users/contributors copy and paste into their terminal. Instead of doing that, consider placing a Makefile in the root of your project which contains the exact same instructions. Thanks to make, all your contributors can now use TAB-completion to run any of the pre-defined make targets.

The following example is part of one of my projects, and I certainly don’t want to type (or even copy) that all the time:

.PHONY: release-into-local-nexus
	mvn versions:set \
	   -DnewVersion=$(TIMESTAMPED_VERSION) \
	-mvn clean deploy scm:tag \
	   -DpushChanges=false \
	   -DskipLocalStaging=true \
	mvn versions:set \
	   -DnewVersion=9999.99.99-SNAPSHOT \

With the above target in place, everyone can now do make release-into-local-nexus instead of typing/copying the commands themselves. Thanks to TAB-completion you just have to do make r<TAB> and confirm with >ENTER> to perform a release.