Add docs, remove useless logic

Author: MaxymVlasov

README.md

@@ -544,12 +544,46 @@ To replicate functionality in `terraform_docs` hook:
 
 ### 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 initialized)
-    * `terraform providers lock`
+> **Note**: The hook requires Terraform 0.14 or later.
+> **Note**: The hook can invoke `terraform providers lock` that can be really slow and requires fetching metadata from remote Terraform registries - not all of that metadata is currently being cached by Terraform.
+
+1. The hook can work in a few different modes: `only-check-is-current-lockfile-cross-platform` with and without [terraform_validate hook](#terraform_validate) and `always-regenerate-lockfile` - only with terraform_validate hook.
+
+    * `only-check-is-current-lockfile-cross-platform` without terraform_validate - only checks that lockfile have all required SHAs for all already added to lockfile providers.
+
+        ```yaml
+        - id: terraform_providers_lock
+          args:
+          - --hook-config=--mode=only-check-is-current-lockfile-cross-platform
+        ```
+
+    * `only-check-is-current-lockfile-cross-platform` with [terraform_validate hook](#terraform_validate) - make up-to-date lockfile by adding/removing providers and only then check that lockfile has all required SHAs.
+
+        > **Note**: Next `terraform_validate` flag requires additional dependency to be installed: `jq`. Also, it could run another slow and time consuming command - `terraform init`
+
+        ```yaml
+        - id: terraform_validate
+          args:
+            - --hook-config=--retry-once-with-cleanup=true
+
+        - id: terraform_providers_lock
+          args:
+          - --hook-config=--mode=only-check-is-current-lockfile-cross-platform
+        ```
+
+    * `always-regenerate-lockfile` only with [terraform_validate hook](#terraform_validate) - regenerate lockfile from scratch. Can be useful for upgrading providers in lockfile to latest versions
+
+        ```yaml
+        - id: terraform_validate
+          args:
+            - --hook-config=--retry-once-with-cleanup=true
+            - --tf-init-args=-upgrade
+
+        - id: terraform_providers_lock
+          args:
+          - --hook-config=--mode=always-regenerate-lockfile
+        ```
 
-    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:
 
@@ -576,6 +610,8 @@ To replicate functionality in `terraform_docs` hook:
 
 1. `terraform_providers_lock` support passing custom arguments to its `terraform init`:
 
+    > **Warning** - DEPRECATION NOTICE: This available only in `no-mode` mode, which will be removed in v2.0. Please provide this keys to [`terraform_validate`](#terraform_validate) hook, which, to take effect, should be called before `terraform_providers_lock`
+
     ```yaml
     - id: terraform_providers_lock
       args:

hooks/_common.sh

@@ -312,6 +312,7 @@ function common::colorify {
 # Outputs:
 #   If failed - print out terraform init output
 #######################################################################
+# TODO: v2.0: Move it inside terraform_validate.sh
 function common::terraform_init {
   local -r command_name=$1
   local -r dir_path=$2

hooks/terraform_providers_lock.sh

@@ -126,17 +126,32 @@ function per_dir_hook_unique_part {
 
   # Available options:
   #   only-check-is-current-lockfile-cross-platform (will be default)
-  #   check-is-there-new-providers-added---run-terraform-init
   #   always-regenerate-lockfile
   #   no-mode # TODO: Remove in 2.0
   [ ! "$mode" ] && mode="no-mode"
 
   if [ "$mode" == "no-mode" ]; then
     common::colorify "yellow" "DEPRECATION NOTICE: We introduced '--mode' flag for this hook.
-Please specify '--hook-config=--mode=always-regenerate-lockfile' in 'args:' if you'd like to continue using this hook as before.
-When v2.x will be introduced - the default mode will be changed.
+If you'd like to continue using this hook as before, please:
+* Specify '--hook-config=--mode=always-regenerate-lockfile' in 'args:'
+* Before 'terraform_providers_lock', add 'terraform_validate' hook with '--hook-config=--retry-once-with-cleanup=true'
+* Move '--tf-init-args=' to 'terraform_validate' hook
 
-You can check available hook modes at https://github.com/antonbabenko/pre-commit-terraform#terraform_providers_lock
+At the end, you should get config like this:
+
+        - id: terraform_validate
+          args:
+            - --hook-config=--retry-once-with-cleanup=true
+            # - --tf-init-args=-upgrade
+
+        - id: terraform_providers_lock
+          args:
+          - --hook-config=--mode=always-regenerate-lockfile
+
+
+Why? When v2.x will be introduced - the default mode will be changed.
+
+You can check available modes for hook at https://github.com/antonbabenko/pre-commit-terraform#terraform_providers_lock
 "
   fi
 
@@ -146,22 +161,15 @@ You can check available hook modes at https://github.com/antonbabenko/pre-commit
     exit 0
   fi
 
-  common::terraform_init 'terraform providers lock' "$dir_path" || {
-    exit_code=$?
-    return $exit_code
-  }
-
-  if [ "$mode" == "check-is-there-new-providers-added---run-terraform-init" ] &&
-    lockfile_contains_all_needed_sha "$platforms_count" &&
-    # Check that lockfile contains all providers
-    #? Don't require `tf init`` for providers, but required `tf init` for modules
-    terraform providers schema -json > /dev/null 2>&1; then
-
-    exit 0
+  if [ "$mode" == "no-mode" ]; then
+    common::terraform_init 'terraform providers lock' "$dir_path" || {
+      exit_code=$?
+      return $exit_code
+    }
   fi
 
   #? Don't require `tf init`` for providers, but required `tf init` for modules
-  #? Could be mitigated by `function match_validate_errors {` from tf_validate hook
+  #? Mitigated by `function match_validate_errors` from terraform_validate hook
   # pass the arguments to hook
   terraform providers lock "${args[@]}"