From 1168e12b2008f8aa9481f6d426c19e22ed64a4c9 Mon Sep 17 00:00:00 2001 From: Tom Pansino <2768420+tpansino@users.noreply.github.com> Date: Tue, 16 Mar 2021 10:31:04 -0700 Subject: [PATCH] Add support for pre-commit hooks Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Add note on regenerating docs manually with pre-commit Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Fix documentation line length Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Fix pre-commit link Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Add YAML three dashes Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Use https protocol in pre-commit example Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Add pre-commit system hook, and some comments Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Sort how-to.md links Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Revert "Sort how-to.md links" This reverts commit e04fa9f4819278de53b869ebbc1a2a59fa662f6d. Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Sort how-to.md links by order of first appearance Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Add whitespace to .pre-commit-hooks.yaml Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Fix pre-commit hooks -> config Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> Fix pre-commit example to use go hook Signed-off-by: Tom Pansino <2768420+tpansino@users.noreply.github.com> --- .pre-commit-hooks.yaml | 31 +++++++++++++++++++++++++ docs/user-guide/how-to.md | 49 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+) create mode 100644 .pre-commit-hooks.yaml diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml new file mode 100644 index 0000000..3375df4 --- /dev/null +++ b/.pre-commit-hooks.yaml @@ -0,0 +1,31 @@ +--- +# Build and run the Go binary from the repo +# REQUIRES: Go v1.16+ installed +- id: terraform-docs-go + name: terraform-docs + description: Generate documentation for Terraform modules (via Go binary) + language: golang + entry: terraform-docs + pass_filenames: false + types: [terraform] + +# Build and run `terraform-docs` assuming it was installed manually +# or via package manager +# REQUIRES: terraform-docs to be installed and on the $PATH +- id: terraform-docs-system + name: terraform-docs + description: Generate documentation for Terraform modules (via locally-installed CLI) + language: system + entry: terraform-docs + pass_filenames: false + types: [terraform] + +# Builds and runs the Docker image from the repo +# REQUIRES: Docker installed +- id: terraform-docs-docker + name: terraform-docs + description: Generate documentation for Terraform modules (via Docker build) + language: docker + entry: terraform-docs + pass_filenames: false + types: [terraform] diff --git a/docs/user-guide/how-to.md b/docs/user-guide/how-to.md index f9f0d9c..9a4afda 100644 --- a/docs/user-guide/how-to.md +++ b/docs/user-guide/how-to.md @@ -123,6 +123,54 @@ jobs: Read more about [terraform-docs GitHub Action] and its configuration and examples. +## Pre-commit Hook + +With [`pre-commit`], you can ensure your Terraform module documentation is kept +up-to-date each time you make a commit. + +First, simply create or update a `.pre-commit-config.yaml` +in the root of your Git repo with at least the following content: + +```yaml +repos: + - repo: https://github.com/terraform-docs/terraform-docs + rev: # For example: "v0.11.2" + hooks: + - id: terraform-docs-go + args: [] # For example: ["--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.) + +Second, install [`pre-commit`] and run `pre-commit` to activate the hooks. + +Then, 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: + +```yaml +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: [] # For example: ["--output-file", "README.md", "./mymodule/path"] + pass_filenames: false +``` + ## Git Hook A simple git hook (`.git/hooks/pre-commit`) added to your local terraform @@ -146,5 +194,6 @@ Please refer to it for complete examples and guides. [sections]: {{< ref "configuration/#sections" >}} [output]: {{< ref "configuration/#output" >}} [terraform-docs GitHub Action]: https://github.com/terraform-docs/gh-actions +[`pre-commit`]: https://pre-commit.com/ [git hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks [pre-commit-terraform]: https://github.com/antonbabenko/pre-commit-terraform