pre-commit-terraform中terraform_docs钩子的深度控制技巧

在Terraform项目中，使用pre-commit-terraform工具自动生成文档是一个常见的实践。然而，当项目结构包含多层嵌套模块时，terraform_docs钩子的默认行为可能会导致在不需要的层级生成文档文件，这往往不是开发者期望的结果。

问题背景

pre-commit-terraform是一个用于在Git提交前自动执行Terraform相关检查的工具集。其中的terraform_docs钩子可以自动为Terraform模块生成文档。当项目结构如下时：

modules/
├── bar/
│   ├── example/
│   │   └── main.tf
│   └── main.tf
└── foo/
    ├── example/
    │   └── main.tf
    └── main.tf

默认情况下，运行pre-commit --all-files会在每个包含.tf文件的目录下生成README.md，包括example子目录。这通常不是开发者想要的行为，因为example目录通常只是示例代码，不需要单独的文档。

解决方案

使用文件匹配模式限制作用范围

最有效的解决方案是在.pre-commit-config.yaml中为terraform_docs钩子添加files参数，精确控制哪些文件会触发文档生成：

repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.86.0
    hooks:
      - id: terraform_docs
        files: ^modules/[^/]+/[^/]+\.(tf|terraform\.lock\.hcl)$
        args:
          - --hook-config=--create-file-if-not-exist=true

这个正则表达式^modules/[^/]+/[^/]+\.(tf|terraform\.lock\.hcl)$的含义是：

• 匹配modules目录下的一级子目录
• 在这些子目录中匹配.tf或.terraform.lock.hcl文件
• 不匹配更深层级的文件

为什么这是最佳实践

1. 精确控制：明确指定哪些层级的文件需要生成文档
2. 性能优化：避免不必要的文件处理和文档生成
3. 符合惯例：大多数情况下，我们只需要为模块根目录生成文档
4. 可维护性：配置清晰，易于理解和修改

技术原理

pre-commit框架的工作机制是：

1. 根据files模式匹配变更文件
2. 对每个匹配的文件，在其所在目录执行钩子脚本
3. 钩子脚本只处理当前目录的文件，不递归处理子目录

因此，通过精确控制files模式，我们可以间接控制文档生成的深度，而不需要修改钩子脚本本身。

注意事项

1. 如果项目结构发生变化，可能需要调整files模式
2. 对于特别复杂的项目结构，可能需要更精细的正则表达式
3. 此方法同样适用于其他pre-commit钩子，如terraform_tflint等

通过这种配置方式，开发者可以既享受自动化文档生成的便利，又保持项目结构的整洁和文档的准确性。