Collection of git hooks for Terraform to be used with pre-commit framework

How to install

1. Install dependencies

pre-commit
terraform-docs (required for terraform_docs hooks)
GNU awk (required for terraform_docs hooks in Terraform 0.12)
TFLint (required for terraform_tflint hook)

MacOS

brew install pre-commit awk terraform-docs tflint

Ubuntu

sudo apt install python-pip3 gawk &&\
pip3 install pre-commit
curl -L "$(curl -s https://api.github.com/repos/segmentio/terraform-docs/releases/latest | grep -o -E "https://.+?-linux-amd64")" > terraform-docs && chmod +x terraform-docs && sudo mv terraform-docs /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/wata727/tflint/releases/latest | grep -o -E "https://.+?_linux_amd64.zip")" > tflint.zip && unzip tflint.zip && rm tflint.zip && sudo mv tflint /usr/bin/

2. Install the pre-commit hook globally

DIR=~/.git-template
git config --global init.templateDir ${DIR}
pre-commit init-templatedir -t pre-commit ${DIR}

3. Add configs and hooks

Step into the repository you want to have the pre-commit hooks installed and run:

git init
cat <<EOF > .pre-commit-config.yaml
- repo: git://github.com/antonbabenko/pre-commit-terraform
  rev: v1.19.0
  hooks:
    - id: terraform_fmt
    - id: terraform_docs
EOF

4. Run

After pre-commit hook has been installed you can run it manually on all files in the repository

pre-commit run -a

Available Hooks

There are several pre-commit hooks to keep Terraform configurations (both *.tf and *.tfvars) and Terragrunt configurations (*.hcl) in a good shape:

Hook name	Description
`terraform_fmt`	Rewrites all Terraform configuration files to a canonical format.
`terraform_validate`	Validates all Terraform configuration files.
`terraform_docs`	Inserts input and output documentation into `README.md`. Recommended.
`terraform_docs_without_aggregate_type_defaults`	Inserts input and output documentation into `README.md` without aggregate type defaults.
`terraform_docs_replace`	Runs `terraform-docs` and pipes the output directly to README.md
`terraform_tflint`	Validates all Terraform configuration files with TFLint.
`terragrunt_fmt`	Rewrites all Terragrunt configuration files (`*.hcl`) to a canonical format.

Check the source file to know arguments used for each hook.

Notes about terraform_docs hooks

terraform_docs and terraform_docs_without_aggregate_type_defaults will insert/update documentation generated by terraform-docs framed by markers:

<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

if they are present in README.md.

terraform_docs_replace replaces the entire README.md rather than doing string replacement between markers. Put your additional documentation at the top of your main.tf for it to be pulled in. The optional --dest argument lets you change the name of the file that gets created/modified.
1. Example:
```
hooks:
  - id: terraform_docs_replace
    args: ['--with-aggregate-type-defaults', '--sort-inputs-by-required', '--dest=TEST.md']
```
It is possible to pass additional arguments to shell scripts when using terraform_docs and terraform_docs_without_aggregate_type_defaults. Send pull-request with the new hook if there is something missing.
terraform-docs works with Terraform 0.12 but support is hackish (it requires awk to be installed) and may contain bugs. You can follow the native support of Terraform 0.12 in terraform-docs in issue #62.

Notes for developers

Python hooks are supported now too. All you have to do is:
1. add a line to the console_scripts array in entry_points in setup.py
2. Put your python script in the pre_commit_hooks folder

Enjoy the clean and documented code!

Authors

This repository is managed by Anton Babenko with help from these awesome contributors.

License

MIT licensed. See LICENSE for full details.

5.7 KiB Raw Blame History