pre-commit, you can ensure your Terraform module documentation is kept
up-to-date each time you make a commit.
simply create or update a
.pre-commit-config.yamlin 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"]You can also include more than one entry under
hooks:to update multiple docs. Just be sure to adjust the
args:to pass the path you want terraform-docs to scan.
pre-committo activate the hooks.
make a Terraform change,
git commit. pre-commit will regenerate your Terraform docs, after which you can rerun
git committo 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.
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
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
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