shini4i / pre-commit-makefile

pre-commit hook to update README with Makefile targets description

🛠 pre-commit-makefile 🛠

This project allows users to automatically update their README.md with descriptions of Makefile targets.

Prerequisites

To use this project, you need to install pre-commit-makefile binary. You can do this by running:

brew install shini4i/tap/pre-commit-makefile

Or by downloading the desired version from releases page.

The expected Makefile format is the following:

.PHONY: help
help: ## print this help
	@echo "Usage: make [target]"
	@grep -E '^[a-z.A-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

.PHONY: test
test: ## run tests
	@go test -v ./... -count=1

Note The content after ## will be used as a target description

Configuration

To start using this project, add the following to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/shini4i/pre-commit-makefile
    rev: v0.2.0
    hooks:
      - id: makefile-validator
      - id: makefile-readme-updater

Validator

Currently, the validator is limited to checking if the Makefile targets have relevant .PHONY definitions.

No additional configuration is required.

Readme Updater

The following comment markers should be added to your README.md:

<!-- BEGINNING OF PRE-COMMIT-MAKEFILE HOOK -->
<!-- END OF PRE-COMMIT-MAKEFILE HOOK -->

The dynamically generated content will be placed between the markers.

Additionally, it is possible to override a few settings by adding the following arguments to your .pre-commit-config.yaml:

args:
  - --readme-path=docs/README.md
  - --section-name=## Usage

Example

The Makefile in this repository will produce the following output:

To install dependencies run:

make install-deps

To build project binary run:

make build

To run tests run:

make test

To run tests with coverage run:

make test-coverage

To remove build artifacts run:

make clean

Note The generated content will be placed under ## Makefile targets section.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.