pre-commit framework
Collection of git hooks for Terraform to be used withHow to install
1. Install dependencies
pre-commit
terraform-docs
(required forterraform_docs
hooks)- GNU
awk
(required forterraform_docs
hooks in Terraform 0.12) TFLint
(required forterraform_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
andterraform_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 yourmain.tf
for it to be pulled in. The optional--dest
argument lets you change the name of the file that gets created/modified.- 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
andterraform_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 requiresawk
to be installed) and may contain bugs. You can follow the native support of Terraform 0.12 interraform-docs
in issue #62.
Notes for developers
- Python hooks are supported now too. All you have to do is:
- add a line to the
console_scripts
array inentry_points
insetup.py
- Put your python script in the
pre_commit_hooks
folder
- add a line to the
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.