docs: Initial docs improvement (#218)

.dockerignore

@@ -1,3 +1,3 @@
 *
 !.dockerignore
-!Dockerfile
+!Dockerfile

.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[{*.{sh,py,md},Dockerfile}]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

.pre-commit-config.yaml

@@ -1,13 +1,31 @@
 repos:
 - repo: git://github.com/pre-commit/pre-commit-hooks
-  rev: v3.4.0
+  rev: v4.0.1
   hooks:
-    - id: check-yaml
+    # Git style
+    - id: check-added-large-files
+    - id: check-merge-conflict
+    - id: check-vcs-permalinks
+    - id: forbid-new-submodules
+    - id: no-commit-to-branch
+
+    # Common errors
     - id: end-of-file-fixer
     - id: trailing-whitespace
-    - id: check-case-conflict
+      args: [--markdown-linebreak-ext=md]
+    - id: check-yaml
     - id: check-merge-conflict
     - id: check-executables-have-shebangs
+
+    # Cross platform
+    - id: check-case-conflict
+
+    # Security
+    - id: detect-aws-credentials
+      args: ['--allow-missing-credentials']
+    - id: detect-private-key
+
+
 - repo: git://github.com/jumanjihouse/pre-commit-hooks
   rev: 2.1.5
   hooks:

CHANGELOG.md

@@ -151,7 +151,7 @@ All notable changes to this project will be documented in this file.
 
 - fix: Change terraform_validate hook functionality for subdirectories with terraform files ([#100](https://github.com/antonbabenko/pre-commit-terraform/issues/100))
 
-### 
+###
 
 configuration for the appropriate working directory.
 

Dockerfile

@@ -2,7 +2,7 @@ FROM ubuntu:18.04
 
 ARG PRE_COMMIT_VERSION="2.11.1"
 ARG TERRAFORM_VERSION="0.15.0"
-ARG TFSEC_VERSION="v0.39.21" 
+ARG TFSEC_VERSION="v0.39.21"
 ARG TERRAFORM_DOCS_VERSION="v0.12.0"
 ARG TFLINT_VERSION="v0.27.0"
 ARG CHECKOV_VERSION="1.0.838"
@@ -33,4 +33,4 @@ RUN tflint --help
 RUN tfsec --help
 RUN checkov --help
 
-ENTRYPOINT [ "pre-commit" ]
+ENTRYPOINT [ "pre-commit" ]

README.md

@@ -1,6 +1,25 @@
 # Collection of git hooks for Terraform to be used with [pre-commit framework](http://pre-commit.com/)
 
-[![Github tag](https://img.shields.io/github/tag/antonbabenko/pre-commit-terraform.svg)](https://github.com/antonbabenko/pre-commit-terraform/releases) ![](https://img.shields.io/maintenance/yes/2021.svg) [![Help Contribute to Open Source](https://www.codetriage.com/antonbabenko/pre-commit-terraform/badges/users.svg)](https://www.codetriage.com/antonbabenko/pre-commit-terraform)
+[![Github tag](https://img.shields.io/github/tag/antonbabenko/pre-commit-terraform.svg)](https://github.com/antonbabenko/pre-commit-terraform/releases) ![maintenance status](https://img.shields.io/maintenance/yes/2021.svg) [![Help Contribute to Open Source](https://www.codetriage.com/antonbabenko/pre-commit-terraform/badges/users.svg)](https://www.codetriage.com/antonbabenko/pre-commit-terraform)
+
+* [How to install](#how-to-install)
+  * [1. Install dependencies](#1-install-dependencies)
+    * [MacOS](#macos)
+    * [Ubuntu 18.04](#ubuntu-1804)
+      * [Ubuntu 20.04](#ubuntu-2004)
+  * [2. Install the pre-commit hook globally](#2-install-the-pre-commit-hook-globally)
+  * [3. Add configs and hooks](#3-add-configs-and-hooks)
+  * [4. Run](#4-run)
+* [Available Hooks](#available-hooks)
+* [Hooks notes](#hooks-notes)
+  * [terraform_docs](#terraform_docs)
+  * [terraform_tflint](#terraform_tflint)
+  * [terraform_tfsec](#terraform_tfsec)
+  * [terraform_validate](#terraform_validate)
+* [Notes for contributors](#notes-for-contributors)
+  * [Run and debug hooks locally](#run-and-debug-hooks-locally)
+* [Authors](#authors)
+* [License](#license)
 
 ## How to install
 
@@ -16,28 +35,46 @@
 
 or build and use the Docker image locally as mentioned below in the `Run` section.
 
-##### MacOS
+#### MacOS
 
 ```bash
 brew install pre-commit gawk terraform-docs tflint tfsec coreutils checkov terrascan
 ```
 
-##### Ubuntu 18.04
+#### Ubuntu 18.04
 
 ```bash
 sudo apt update
 sudo apt install -y gawk unzip software-properties-common
 sudo add-apt-repository ppa:deadsnakes/ppa
 sudo apt install -y python3.7 python3-pip
+python3 -m pip install --upgrade pip
 pip3 install pre-commit
 curl -L "$(curl -s https://api.github.com/repos/terraform-docs/terraform-docs/releases/latest | grep -o -E "https://.+?-linux-amd64.tar.gz")" > terraform-docs.tgz && tar xzf terraform-docs.tgz && chmod +x terraform-docs && sudo mv terraform-docs /usr/bin/
 curl -L "$(curl -s https://api.github.com/repos/terraform-linters/tflint/releases/latest | grep -o -E "https://.+?_linux_amd64.zip")" > tflint.zip && unzip tflint.zip && rm tflint.zip && sudo mv tflint /usr/bin/
-curl -L "$(curl -s https://api.github.com/repos/tfsec/tfsec/releases/latest | grep -o -E "https://.+?tfsec-linux-amd64")" > tfsec && chmod +x tfsec && sudo mv tfsec /usr/bin/
+curl -L "$(curl -s https://api.github.com/repos/aquasecurity/tfsec/releases/latest | grep -o -E "https://.+?tfsec-linux-amd64" | head -n 1)" > tfsec && chmod +x tfsec && sudo mv tfsec /usr/bin/
 curl -L "$(curl -s https://api.github.com/repos/accurics/terrascan/releases/latest | grep -o -E "https://.+?_Linux_x86_64.tar.gz")" > terrascan.tar.gz && tar -xf terrascan.tar.gz terrascan && rm terrascan.tar.gz && sudo mv terrascan /usr/bin/
 python3.7 -m pip install -U checkov
 ```
 
+##### Ubuntu 20.04
+
+```bash
+sudo apt update
+sudo apt install -y gawk unzip software-properties-common
+sudo apt install -y python3 python3-pip
+python3 -m pip install --upgrade pip
+pip3 install pre-commit
+curl -L "$(curl -s https://api.github.com/repos/terraform-docs/terraform-docs/releases/latest | grep -o -E "https://.+?-linux-amd64.tar.gz")" > terraform-docs.tgz && tar -xzf terraform-docs.tgz terraform-docs && chmod +x terraform-docs && sudo mv terraform-docs /usr/bin/
+curl -L "$(curl -s https://api.github.com/repos/terraform-linters/tflint/releases/latest | grep -o -E "https://.+?_linux_amd64.zip")" > tflint.zip && unzip tflint.zip && rm tflint.zip && sudo mv tflint /usr/bin/
+curl -L "$(curl -s https://api.github.com/repos/aquasecurity/tfsec/releases/latest | grep -o -E "https://.+?tfsec-linux-amd64" | head -n 1)" > tfsec && chmod +x tfsec && sudo mv tfsec /usr/bin/
+curl -L "$(curl -s https://api.github.com/repos/accurics/terrascan/releases/latest | grep -o -E "https://.+?_Linux_x86_64.tar.gz")" > terrascan.tar.gz && tar -xf terrascan.tar.gz terrascan && rm terrascan.tar.gz && sudo mv terrascan /usr/bin/
+pip3 install -U checkov
+```
+
+
 ### 2. Install the pre-commit hook globally
+
 Note: not needed if you use the Docker image
 
 ```bash
@@ -71,6 +108,7 @@ pre-commit run -a
 ```
 
 or you can also build and use the provided Docker container, which wraps all dependencies by
+
 ```bash
 # first building it
 docker build -t pre-commit .
@@ -83,80 +121,88 @@ docker run -v $(pwd):/lint -w /lint pre-commit run -a
 
 There are several [pre-commit](https://pre-commit.com/) 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 (requires terraform-docs v0.10.0 or later)                                                           |
-| `terraform_tflint`                               | Validates all Terraform configuration files with [TFLint](https://github.com/terraform-linters/tflint).                              |
-| `terragrunt_fmt`                                 | Rewrites all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) to a canonical format. |
-| `terragrunt_validate`                            | Validates all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`)                       |
-| `terraform_tfsec`                                | [TFSec](https://github.com/liamg/tfsec) static analysis of terraform templates to spot potential security issues.     |
-| `checkov`                                | [checkov](https://github.com/bridgecrewio/checkov) static analysis of terraform templates to spot potential security issues.     |
-| `terrascan`                                | [terrascan](https://github.com/accurics/terrascan) Detect compliance and security violations. |
+| Hook name                                        | Description                                                                                                                                      |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `terraform_fmt`                                  | Rewrites all Terraform configuration files to a canonical format. [Hook notes](#terraform_docs)                                                  |
+| `terraform_validate`                             | Validates all Terraform configuration files. [Hook notes](#terraform_validate)                                                                   |
+| `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](https://github.com/terraform-linters/tflint). [Hook notes](#terraform_tflint).         |
+| `terragrunt_fmt`                                 | Rewrites all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) to a canonical format.                       |
+| `terragrunt_validate`                            | Validates all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`)                                             |
+| `terraform_tfsec`                                | [TFSec](https://github.com/liamg/tfsec) static analysis of terraform templates to spot potential security issues. [Hook notes](#terraform_tfsec) |
+| `checkov`                                        | [checkov](https://github.com/bridgecrewio/checkov) static analysis of terraform templates to spot potential security issues.                     |
+| `terrascan`                                      | [terrascan](https://github.com/accurics/terrascan) Detect compliance and security violations.                                                    |
 
 Check the [source file](https://github.com/antonbabenko/pre-commit-terraform/blob/master/.pre-commit-hooks.yaml) to know arguments used for each hook.
 
-## Notes about terraform_docs hooks
+## Hooks notes
+
+### terraform_docs
 
 1. `terraform_docs` and `terraform_docs_without_aggregate_type_defaults` will insert/update documentation generated by [terraform-docs](https://github.com/terraform-docs/terraform-docs) framed by markers:
-```txt
-<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 
-<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
-```
-if they are present in `README.md`.
+    ```txt
+    <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+
+    <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+    ```
+
+    if they are present in `README.md`.
 
-1. `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. This hook requires terraform-docs v0.10.0 or later.
+2. `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.
+
+    Example:
 
-    1. Example:
     ```yaml
     hooks:
       - id: terraform_docs_replace
         args: ['--sort-by-required', '--dest=TEST.md']
     ```
 
-1. 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.
+3. 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
+### terraform_tflint
 
 1. `terraform_tflint` supports custom arguments so you can enable module inspection, deep check mode etc.
 
-    1. Example:
+    Example:
+
     ```yaml
     hooks:
       - id: terraform_tflint
         args: ['--args=--deep']
     ```
 
     In order to pass multiple args, try the following:
+
     ```yaml
      - id: terraform_tflint
        args:
           - '--args=--deep'
           - '--args=--enable-rule=terraform_documented_variables'
     ```
 
-1. When you have multiple directories and want to run `tflint` in all of them and share single config file it is impractical to hard-code the path to `.tflint.hcl` file. The solution is to use `__GIT_WORKING_DIR__` placeholder which will be replaced by `terraform_tflint` hooks with Git working directory (repo root) at run time. For example:
+3. When you have multiple directories and want to run `tflint` in all of them and share single config file it is impractical to hard-code the path to `.tflint.hcl` file. The solution is to use `__GIT_WORKING_DIR__` placeholder which will be replaced by `terraform_tflint` hooks with Git working directory (repo root) at run time. For example:
 
-   ```yaml
-   hooks:
-     - id: terraform_tflint
-       args:
-         - '--args=--config=__GIT_WORKING_DIR__/.tflint.hcl'
-   ```
+    ```yaml
+    hooks:
+      - id: terraform_tflint
+        args:
+          - '--args=--config=__GIT_WORKING_DIR__/.tflint.hcl'
+    ```
 
 
-## Notes about terraform_tfsec hooks
+### terraform_tfsec
 
 1. `terraform_tfsec` will consume modified files that pre-commit
     passes to it, so you can perform whitelisting of directories
     or files to run against via [files](https://pre-commit.com/#config-files)
     pre-commit flag
 
-    1. Example:
+    Example:
+
     ```yaml
     hooks:
       - id: terraform_tfsec
@@ -167,44 +213,51 @@ if they are present in `README.md`.
     only such that the underlying `tfsec` tool can run against changed files in this
     directory, ignoring any other folders at the root level
 
-1. To ignore specific warnings, follow the convention from the
+2. To ignore specific warnings, follow the convention from the
 [documentation](https://github.com/liamg/tfsec#ignoring-warnings).
-    1. Example:
+
+    Example:
+
     ```hcl
     resource "aws_security_group_rule" "my-rule" {
         type = "ingress"
         cidr_blocks = ["0.0.0.0/0"] #tfsec:ignore:AWS006
     }
     ```
 
-## Notes about terraform_validate hooks
+### terraform_validate
 
 1. `terraform_validate` supports custom arguments so you can pass supported no-color or json flags.
 
-    1. Example:
+    Example:
+
     ```yaml
     hooks:
       - id: terraform_validate
         args: ['--args=-json']
     ```
 
     In order to pass multiple args, try the following:
+
     ```yaml
      - id: terraform_validate
        args:
           - '--args=-json'
           - '--args=-no-color'
     ```
-1. `terraform_validate` also supports custom environment variables passed to the pre-commit runtime
 
-    1. Example:
+2. `terraform_validate` also supports custom environment variables passed to the pre-commit runtime
+
+    Example:
+
     ```yaml
     hooks:
       - id: terraform_validate
         args: ['--envs=AWS_DEFAULT_REGION="us-west-2"']
     ```
 
     In order to pass multiple args, try the following:
+
     ```yaml
      - id: terraform_validate
        args:
@@ -213,22 +266,37 @@ if they are present in `README.md`.
           - '--envs=AWS_SECRET_ACCESS_KEY="asecretkey"'
     ```
 
-1. It may happen that Terraform working directory (`.terraform`) already exists but not in the best condition (eg, not initialized modules, wrong version of Terraform, etc). To solve this problem you can find and delete all `.terraform` directories in your repository using this command:
+3. It may happen that Terraform working directory (`.terraform`) already exists but not in the best condition (eg, not initialized modules, wrong version of Terraform, etc). To solve this problem you can find and delete all `.terraform` directories in your repository using this command:
 
     ```shell
     find . -type d -name ".terraform" -print0 | xargs -0 rm -r
     ```
 
    `terraform_validate` hook will try to reinitialize them before running `terraform validate` command.
 
-## Notes for developers
+## Notes for contributors
 
 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 `setup.py`
-    1. Put your python script in the `pre_commit_hooks` folder
+    2. Put your python script in the `pre_commit_hooks` folder
 
 Enjoy the clean, valid, and documented code!
 
+### Run and debug hooks locally
+
+```bash
+pre-commit try-repo {-a} /path/to/local/pre-commit-terraform/repo {hook_name}
+```
+
+I.e.
+
+```bash
+pre-commit try-repo /mnt/c/Users/tf/pre-commit-terraform terraform_fmt # Run only `terraform_fmt` check
+pre-commit try-repo -a ~/pre-commit-terraform # run all existing checks from repo
+```
+
+Running `pre-commit` with `try-repo` ignores all arguments specified in `.pre-commit-config.yaml`.
+
 ## Authors
 
 This repository is managed by [Anton Babenko](https://github.com/antonbabenko) with help from [these awesome contributors](https://github.com/antonbabenko/pre-commit-terraform/graphs/contributors).