pre-commit-terraform项目中terraform_docs钩子的输出文件配置问题解析

在pre-commit-terraform项目的使用过程中，当用户配置了terraform-docs工具的output.file参数时，会遇到一个典型的输出文件内容异常问题。这个问题会导致生成的文档中包含不必要的状态信息，而非预期的纯文档内容。

问题现象

当用户在.terraform-docs.yml配置文件中指定了output.file参数（如设置为"./README.md"），并同时启用了标准标记(--use-standard-markers=true)时，terraform-docs工具会直接更新指定文件并在标准输出中打印状态信息（如"README.md updated successfully"）。

由于pre-commit-terraform的terraform_docs钩子实现会无条件地将标准输出重定向到目标文件，最终导致目标文件中不仅包含预期的文档内容，还包含了工具的状态输出信息。具体表现为生成的README.md文件中出现如下内容：

<!-- BEGIN_TF_DOCS -->
README.md updated successfully
<!-- END_TF_DOCS -->

问题根源

这个问题的本质在于两个方面的行为冲突：

1. terraform-docs工具本身的行为：当配置了output.file参数时，工具会自行处理文件写入操作，并在标准输出中打印状态信息而非文档内容。

2. pre-commit-terraform钩子的行为：钩子实现假设terraform-docs总是将文档内容输出到标准输出，因此无条件地将标准输出重定向到目标文件。

这种设计上的不匹配导致了状态信息被错误地写入文档文件。

解决方案

项目维护团队在1.92.2版本中修复了这个问题。修复方案主要涉及对钩子行为的调整：

1. 当检测到用户配置了output.file参数时，钩子应避免再次重定向输出到文件。

2. 正确处理terraform-docs工具的输出流，确保状态信息不会被误写入文档文件。

最佳实践建议

为了避免类似问题，用户在使用pre-commit-terraform的terraform_docs钩子时应注意：

1. 如果使用.terraform-docs.yml配置文件，应确保output.file配置与钩子的--path-to-file参数一致。

2. 优先使用最新版本的pre-commit-terraform，以获得最稳定的行为。

3. 在复杂配置场景下，建议先单独测试terraform-docs命令的输出，再整合到pre-commit流程中。

这个案例也展示了开源工具链集成时常见的接口匹配问题，提醒开发者在设计工具间的交互时需要考虑各种使用场景的兼容性。