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

@@ -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]

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: <VERSION TAG OR SHA TO USE> # For example: "v0.11.2"
+    hooks:
+      - id: terraform-docs-go
+        args: [<ARGS TO PASS INCLUDING PATH>]  # 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: [<ARGS TO PASS INCLUDING PATH>]  # 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