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

How to install

Step 1

On MacOSX install the pre-commit package

brew install pre-commit

For other operating systems check the official documentation

Step 2

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

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

Step 3

Install the pre-commit hook

pre-commit install

Step 4

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) in a good shape:

• terraform_fmt - Rewrites all Terraform configuration files to a canonical format.
• terraform_validate_no_variables - Validates all Terraform configuration files without checking whether all required variables were set.
• terraform_validate_with_variables - Validates all Terraform configuration files and checks whether all required variables were specified.
• 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

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

Notes about hooks

1. terraform_validate_no_variables and terraform_validate_with_variables will not work if variables are being set dynamically (eg, when using Terragrunt). Use terragrunt validate command instead.

2. terraform_docs and terraform_docs_without_aggregate_type_defaults will insert/update documentation generated by terraform-docs between markers - <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK --> and <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK --> if they are present in README.md. Make sure that terraform-docs is installed.

3. 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']
   

4. 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.

Notes for developers

1. Python hooks are supported now too. All you have to do is:
   1. add a line to the console_sripts 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.