pre-commit Hooks

Since v0.12.0

With pre-commit, you can ensure your Terraform module documentation is kept up-to-date each time you make a commit.

  1. simply create or update a .pre-commit-config.yaml in the root of your Git repo with at least the following content:

    repos:
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: "<VERSION, TAG, OR SHA TO USE>"             # e.g. "v0.11.2"
    hooks:
      - id: terraform-docs-go
        args: ["ARGS", "TO PASS", "INCLUDING PATH"]  # e.g. ["--output-file", "README.md", "./mymodule/path"]

  2. install pre-commit and run pre-commit to activate the hooks.

  3. make a Terraform change, git add and git commit. pre-commit will regenerate your Terraform docs, after which you can rerun git add and git commit to commit the code and doc changes together.

You can also regenerate the docs manually by running pre-commit -a terraform-docs.

pre-commit via Docker

The pre-commit hook can also be run via Docker, for those who don’t have Go installed. Just use id: terraform-docs-docker in the previous example.

This will build the Docker image from the repo, which can be quite slow. To download the pre-built image instead, change your .pre-commit-config.yaml to:

repos:
  - repo: local
    hooks:
      - id: terraform-docs
        name: terraform-docs
        language: docker_image
        entry: quay.io/terraform-docs/terraform-docs:latest  # or, change latest to pin to a specific version
        args: ["ARGS", "TO PASS", "INCLUDING PATH"]          # e.g. ["--output-file", "README.md", "./mymodule/path"]
        pass_filenames: false

Git Hook

A simple git hook (.git/hooks/pre-commit) added to your local terraform repository can keep your Terraform module documentation up to date whenever you make a commit. See also git hooks documentation.

#!/bin/sh

# Keep module docs up to date
for d in modules/*; do
  if terraform-docs md "$d" > "$d/README.md"; then
    git add "./$d/README.md"
  fi
done

Edit on GitHub

← GitHub Action