Skip to content
Go to file

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

Github tag Help Contribute to Open Source

How to install

1. Install dependencies

  • pre-commit
  • terraform-docs required for terraform_docs hooks. GNU awk is required if using terraform-docs older than 0.8.0 with Terraform 0.12.
  • TFLint required for terraform_tflint hook.
  • TFSec required for terraform_tfsec hook.
  • coreutils required for terraform_validate hook on macOS (due to use of realpath).
brew tap liamg/tfsec
brew install pre-commit gawk terraform-docs tflint tfsec coreutils
sudo apt install python3-pip gawk &&\
pip3 install pre-commit
curl -L "$(curl -s | grep -o -E "https://.+?-linux-amd64")" > terraform-docs && chmod +x terraform-docs && sudo mv terraform-docs /usr/bin/
curl -L "$(curl -s | grep -o -E "https://.+?")" > && unzip && rm && sudo mv tflint /usr/bin/
env GO111MODULE=on go get -u

2. Install the pre-commit hook globally

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://
  rev: <VERSION> # Get the latest from:
    - id: terraform_fmt
    - id: terraform_docs

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 Recommended.
terraform_docs_without_aggregate_type_defaults Inserts input and output documentation into without aggregate type defaults.
terraform_docs_replace Runs terraform-docs and pipes the output directly to
terraform_tflint Validates all Terraform configuration files with TFLint.
terragrunt_fmt Rewrites all Terragrunt configuration files (*.hcl) to a canonical format.
terraform_tfsec TFSec static analysis of terraform templates to spot potential security issues.

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

Notes about terraform_docs hooks

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


if they are present in

  1. terraform_docs_replace replaces the entire rather than doing string replacement between markers. Put your additional documentation at the top of your for it to be pulled in. The optional --dest argument lets you change the name of the file that gets created/modified.

    1. Example:
      - id: terraform_docs_replace
        args: ['--with-aggregate-type-defaults', '--sort-inputs-by-required', '']
  2. 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 about terraform_tflint hooks

  1. terraform_tflint supports custom arguments so you can enable module inspection, deep check mode etc.

    1. Example:
      - id: terraform_tflint
        args: ['args=--deep']

    In order to pass multiple args, try the following:

     - id: terraform_tflint
          - 'args=--deep'
          - 'args=--enable-rule=terraform_documented_variables'

Notes about terraform_tfsec hooks

  1. terraform_tfsec will recurse all directories/modules.
  2. To ignore specific warnings, follow the convention from the documentation.
    1. Example:
    resource "aws_security_group_rule" "my-rule" {
        type = "ingress"
        cidr_blocks = [""] #tfsec:ignore:AWS006

Notes for developers

  1. 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
    2. Put your python script in the pre_commit_hooks folder

Enjoy the clean and documented code!


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


MIT licensed. See LICENSE for full details.

You can’t perform that action at this time.