pre-commit git hooks to take care of Terraform configurations
Branch: master
Clone or download
Pull request Compare This branch is even with antonbabenko:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

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

Github tag Help Contribute to Open Source

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://
  rev: v1.7.4
    - id: terraform_fmt
    - id: terraform_docs

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

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 Make sure that terraform-docs is installed.

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