cloudposse / pre-commit-makefile

Useful Git http://pre-commit.com hooks when using Makefiles such as generating documentation in README.md.

pre-commit-makefile

Useful Git hooks when using Makefiles such as generating documentation in README.md.

It uses Yelp's pre-commit framework for adding git hooks locally.

Dependencies

• bash
• perl
• git

Usage

Step 1: Install the pre-commit package (MAC OS)

brew install pre-commit

For operating systems, other than macOS, check the official documentation.

Step 2: Add the following to .pre-commit-config.yaml

cat <<EOF > .pre-commit-config.yaml
- repo: git://github.com/johncblandii/pre-commit-makefile
  rev: master
  hooks:
    - id: makefile-doc
EOF

Step 3: Install the git pre-commit hook to your local project

pre-commit install

If you want to run the checks on-demand (outside of git hooks), run after you when through the setup below:

pre-commit run --all-files --verbose

Step 4: Create a Makefile and define a make help target

Define make help target that outputs a list of targets with documentation. You can follow the self-documenting Makefile format or take the starter test/Makefile.

Step 5: Add Markers in README.md

Add the following markers to the README.md files that are in the same directory as the Makefile:

<!-- START makefile-doc -->

<!-- END makefile-doc -->

makefile-doc will add or update documentation generated by make help between the markers in the README.md files that are located in the same folder as the Makefile.

It will only scan for files named strictly Makefile in the all directories and insert the documentation into README.md files in the same directories.

License

The code in this repo is licensed under the MIT License.