From eec9c884a1fed9ef87aa71ac14031898c14323f4 Mon Sep 17 00:00:00 2001 From: Maksym Vlasov Date: Thu, 17 Oct 2019 14:50:16 +0300 Subject: [PATCH] Improve installation instructions and make README more readable (#72) --- README.md | 68 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index d61fe891b..ec268998f 100644 --- a/README.md +++ b/README.md @@ -4,21 +4,42 @@ ## How to install -### Step 1 +### 1. Install dependencies -On MacOSX install the `pre-commit` and `awk` (required for Terraform 0.12) package +* [`pre-commit`](http://pre-commit.com/#install) +* [`terraform-docs`](https://github.com/segmentio/terraform-docs) (required for `terraform_docs` hooks) +* GNU `awk` (required for `terraform_docs` hooks in Terraform 0.12) +* [`TFLint`](https://github.com/wata727/tflint) (required for `terraform_tflint` hook) + +##### MacOS + +```bash +brew install pre-commit awk terraform-docs tflint +``` + +##### Ubuntu ```bash -brew install pre-commit awk +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/ ``` -For other operating systems check the [official documentation](http://pre-commit.com/#install) +### 2. Install the pre-commit hook globally + +```bash +DIR=~/.git-template +git config --global init.templateDir ${DIR} +pre-commit init-templatedir -t pre-commit ${DIR} +``` -### Step 2 +### 3. Add configs and hooks Step into the repository you want to have the pre-commit hooks installed and run: ```bash +git init cat < .pre-commit-config.yaml - repo: git://github.com/antonbabenko/pre-commit-terraform rev: v1.19.0 @@ -28,15 +49,7 @@ cat < .pre-commit-config.yaml EOF ``` -### Step 3 - -Install the pre-commit hook - -```bash -pre-commit install -``` - -### Step 4 +### 4. Run After pre-commit hook has been installed you can run it manually on all files in the repository @@ -47,19 +60,28 @@ pre-commit run -a ## Available Hooks There are several [pre-commit](http://pre-commit.com/) hooks to keep Terraform configurations (both `*.tf` and `*.tfvars`) and Terragrunt configurations (`*.hcl`) in a good shape: -* `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](https://github.com/wata727/tflint). -* `terragrunt_fmt` - Rewrites all Terragrunt configuration files (`*.hcl`) to a canonical format. + +| 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](https://github.com/wata727/tflint). | +| `terragrunt_fmt` | Rewrites all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) to a canonical format. | 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 hooks +## Notes about terraform_docs hooks -1. `terraform_docs` and `terraform_docs_without_aggregate_type_defaults` will insert/update documentation generated by [terraform-docs](https://github.com/segmentio/terraform-docs) between markers - `` and `` if they are present in `README.md`. Make sure that `terraform-docs` is installed. +1. `terraform_docs` and `terraform_docs_without_aggregate_type_defaults` will insert/update documentation generated by [terraform-docs](https://github.com/segmentio/terraform-docs) framed by markers: +```txt + + + +``` +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.