docs: Add terraform_fmt usage instructions and how-to debug script with args (#242)

.github/CONTRIBUTING.md

@@ -28,6 +28,14 @@ pre-commit try-repo -a ~/pre-commit-terraform # run all existing checks from rep
 
 Running `pre-commit` with `try-repo` ignores all arguments specified in `.pre-commit-config.yaml`.
 
+If you need to test hook with arguments, follow [pre-commit doc](https://pre-commit.com/#arguments-pattern-in-hooks) to test hooks.
+
+For example, to test that the [`terraform_fmt`](../README.md#terraform_fmt) hook works fine with arguments:
+
+```bash
+/tmp/pre-commit-terraform/terraform_fmt.sh --args=-diff --args=-write=false test-dir/main.tf test-dir/vars.tf
+```
+
 ## Run hook performance test
 
 To check is your improvement not violate performance, we have dummy execution time tests.

README.md

@@ -14,6 +14,7 @@ Want to Contribute? Check [open issues](https://github.com/antonbabenko/pre-comm
   * [checkov](#checkov)
   * [terraform_docs](#terraform_docs)
   * [terraform_docs_replace](#terraform_docs_replace)
+  * [terraform_fmt](#terraform_fmt)
   * [terraform_providers_lock](#terraform_providers_lock)
   * [terraform_tflint](#terraform_tflint)
   * [terraform_tfsec](#terraform_tfsec)
@@ -183,8 +184,8 @@ There are several [pre-commit](https://pre-commit.com/) hooks to keep Terraform
 | `terraform_docs_replace`                         | Runs `terraform-docs` and pipes the output directly to README.md                                                                                                                                                                             |
 | `terraform_docs_without_aggregate_type_defaults` | Inserts input and output documentation into `README.md` without aggregate type defaults. Hook notes same as for [terraform_docs](#terraform_docs)                                                                                            |
 | `terraform_docs`                                 | Inserts input and output documentation into `README.md`. Recommended. [Hook notes](#terraform_docs)                                                                                                                                          |
-| `terraform_fmt`                                  | Rewrites all Terraform configuration files to a canonical format. [Hook notes](#terraform_docs)                                                                                                                                              |
+| `terraform_fmt`                                  | Rewrites all Terraform configuration files to a canonical format. [Hook notes](#terraform_fmt)                                                                                                                                               |
-| `terraform_providers_lock`                       | Updates provider signatures in [dependency lock files](https://www.terraform.io/docs/cli/commands/providers/lock.html). [Hook notes](#terraform_providers_lock)
+| `terraform_providers_lock`                       | Updates provider signatures in [dependency lock files](https://www.terraform.io/docs/cli/commands/providers/lock.html). [Hook notes](#terraform_providers_lock)                                                                              |
 | `terraform_tflint`                               | Validates all Terraform configuration files with [TFLint](https://github.com/terraform-linters/tflint). [Available TFLint rules](https://github.com/terraform-linters/tflint/tree/master/docs/rules#rules). [Hook notes](#terraform_tflint). |
 | `terraform_tfsec`                                | [TFSec](https://github.com/liamg/tfsec) static analysis of terraform templates to spot potential security issues. [Hook notes](#terraform_tfsec)                                                                                             |
 | `terraform_validate`                             | Validates all Terraform configuration files. [Hook notes](#terraform_validate)                                                                                                                                                               |
@@ -243,6 +244,50 @@ Example:
     - --dest=TEST.md
 ```
 
+### terraform_fmt
+
+1. `terraform_fmt` supports custom arguments so you can pass [supported flags](https://www.terraform.io/docs/cli/commands/fmt.html#usage). Eg:
+
+    ```yaml
+     - id: terraform_fmt
+       args:
+         - --args=-no-color
+         - --args=-diff
+         - --args=-write=false
+    ```
+
+### terraform_providers_lock
+
+1. The hook requires Terraform 0.14 or later.
+2. The hook invokes two operations that can be really slow:
+    * `terraform init` (in case `.terraform` directory is not initialised)
+    * `terraform providers lock`.
+
+    Both operations require downloading data from remote Terraform registries, and not all of that downloaded data or meta-data is currently being cached by Terraform.
+
+3. `terraform_providers_lock` supports custom arguments:
+
+    ```yaml
+     - id: terraform_providers_lock
+       args:
+          - '--args=-platform=windows_amd64'
+          - '--args=-platform=darwin_amd64'
+    ```
+
+4. 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:
+
+    ```bash
+    echo "
+    function rm_terraform {
+        find . -name ".terraform*" -print0 | xargs -0 rm -r
+    }
+    " >>~/.bashrc
+
+    # Reload shell and use `rm_terraform` command in repo root
+    ```
+
+    `terraform_providers_lock` hook will try to reinitialize them before running `terraform providers lock` command.
+
 ### terraform_tflint
 
 1. `terraform_tflint` supports custom arguments so you can enable module inspection, deep check mode etc.
@@ -344,44 +389,6 @@ Example:
 
     **Warning:** If you use Terraform workspaces, DO NOT use this workaround ([details](https://github.com/antonbabenko/pre-commit-terraform/issues/203#issuecomment-918791847)). Wait to [`force-init`](https://github.com/antonbabenko/pre-commit-terraform/issues/224) option implementation
 
-### terraform_providers_lock
-
-1.  The hook requires Terraform 0.14 or later.
-
-1.  The hook invokes two operations that can be really slow:
-    `terraform init` (in case `.terraform` directory is not initialised)
-    and `terraform providers lock`. Both operations require downloading
-    data from remote Terraform registries, and not all of that
-    downloaded data or meta-data is currently being cached by Terraform.
-
-1.  `terraform_providers_lock` supports custom arguments.
-
-    Example:
-
-    ```yaml
-    hooks:
-      - id: terraform_providers_lock
-        args: ['--args=-platform=windows_amd64']
-    ```
-
-    In order to pass multiple args, try the following:
-
-    ```yaml
-     - id: terraform_providers_lock
-       args:
-          - '--args=-platform=windows_amd64'
-          - '--args=-platform=darwin_amd64'
-    ```  
-
-1.  It may happen that Terraform working directory (`.terraform`) already exists but is outdated
-    (e.g. 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 -prune -print -exec rm -rf {} \;
-    ```
-
-    `terraform_providers_lock` hook will try to reinitialize them before running `terraform providers lock` command.
 
 ## Authors