feat(terraform_docs): Add terraform-docs default markers support and describe how to migrate to them

README.md

@@ -486,13 +486,15 @@ Unlike most other hooks, this hook triggers once if there are any changed files
     * create a documentation file
     * extend existing documentation file by appending markers to the end of the file (see item 1 above)
     * use different filename for the documentation (default is `README.md`)
+    * use the same insertion markers as `terraform-docs`, i.e. `<!-- BEGIN_TF_DOCS -->...<!-- END_TF_DOCS -->`
 
     ```yaml
     - id: terraform_docs
       args:
         - --hook-config=--path-to-file=README.md        # Valid UNIX path. I.e. ../TFDOC.md or docs/README.md etc.
         - --hook-config=--add-to-existing-file=true     # Boolean. true or false
         - --hook-config=--create-file-if-not-exist=true # Boolean. true or false
+        - --hook-config=--use-standard-markers=true     # Boolean. Defaults to false. Set to true for compatibility with terraform-docs
     ```
 
 4. You can provide [any configuration available in `terraform-docs`](https://terraform-docs.io/user-guide/configuration/) as an argument to `terraform_doc` hook, for example:

hooks/terraform_docs.sh

@@ -7,6 +7,11 @@ readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 # shellcheck source=_common.sh
 . "$SCRIPT_DIR/_common.sh"
 
+# set up default insertion markers.  These will be changed to the markers used by
+# terraform-docs if the hook config contains `--use-standard-markers=true`
+insertion_marker_begin="<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->"
+insertion_marker_end="<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->"
+
 function main {
   common::initialize "$SCRIPT_DIR"
   common::parse_cmdline "$@"
@@ -37,6 +42,31 @@ function terraform_docs_ {
   # Get hook settings
   IFS=";" read -r -a configs <<< "$hook_config"
 
+  use_standard_markers=false
+
+  for arg in "${configs[@]}"; do
+    # remove leading whitespace characters
+    arg="${arg#"${arg%%[![:space:]]*}"}"
+    # Check if the argument starts with 'use-standard-markers='
+    if [[ $arg == '--use-standard-markers='* ]]; then
+      # Extract the value after '=' and store it in the use_standard_markers variable
+      use_standard_markers="${arg#*=}"
+
+      # Remove the argument from the array and break out of the loop
+      configs=("${configs[@]/$arg/}")
+      break
+    fi
+  done
+
+  echo "Use standard markers: $use_standard_markers"
+  echo "Remaining hook config: ${configs[@]}"
+
+  if [ "$use_standard_markers" = true ] ; then
+    # update the insertion markers to those used by terraform-docs
+    insertion_marker_begin="<!-- BEGIN_TF_DOCS -->"
+    insertion_marker_end="<!-- END_TF_DOCS -->"
+  fi
+
   local hack_terraform_docs
   hack_terraform_docs=$(terraform version | sed -n 1p | grep -c 0.12) || true
 
@@ -178,10 +208,12 @@ function terraform_docs {
       dir="$(dirname "$text_file")"
 
       mkdir -p "$dir"
+
+      # Use of insertion markers, where there is no existing README file
       {
         echo -e "# ${PWD##*/}\n"
-        echo "<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->"
-        echo "<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->"
+        echo $insertion_marker_begin
+        echo $insertion_marker_end
       } >> "$text_file"
     fi
 
@@ -193,11 +225,12 @@ function terraform_docs {
     # and if not - append "hook markers" to the end of file.
     #
     if $add_to_existing; then
-      HAVE_MARKER=$(grep -o '<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->' "$text_file" || exit 0)
+      HAVE_MARKER=$(grep -o "$insertion_marker_begin" "$text_file" || exit 0)
 
       if [ ! "$HAVE_MARKER" ]; then
-        echo "<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->" >> "$text_file"
-        echo "<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->" >> "$text_file"
+        # Use of insertion markers, where addToExisting=true, with no markers in the existing file
+        echo $insertion_marker_begin >> "$text_file"
+        echo $insertion_marker_end >> "$text_file"
       fi
     fi
 
@@ -218,8 +251,10 @@ function terraform_docs {
       rm -f "$tmp_file_docs_tf"
     fi
 
+    # Use of insertion markers to insert the terraform-docs output between the markers
     # Replace content between markers with the placeholder - https://stackoverflow.com/questions/1212799/how-do-i-extract-lines-between-two-line-delimiters-in-perl#1212834
-    perl -i -ne 'if (/BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK/../END OF PRE-COMMIT-TERRAFORM DOCS HOOK/) { print $_ if /BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK/; print "I_WANT_TO_BE_REPLACED\n$_" if /END OF PRE-COMMIT-TERRAFORM DOCS HOOK/;} else { print $_ }' "$text_file"
+    perl_expression="if (/$insertion_marker_begin/../$insertion_marker_end/) { print \$_ if /$insertion_marker_begin/; print \"I_WANT_TO_BE_REPLACED\\n\$_\" if /$insertion_marker_end/;} else { print \$_ }"
+    perl -i -ne "$perl_expression" "$text_file"
 
     # Replace placeholder with the content of the file
     perl -i -e 'open(F, "'"$tmp_file"'"); $f = join "", <F>; while(<>){if (/I_WANT_TO_BE_REPLACED/) {print $f} else {print $_};}' "$text_file"