pre-commit-terraform项目中terraform_docs钩子的include与footer-from配置指南

在基础设施即代码（IaC）开发中，自动生成文档是提升项目可维护性的重要实践。terraform-docs作为Terraform生态中的文档生成工具，配合pre-commit框架使用时，其include和footer-from功能常会遇到路径解析问题。本文将深入解析这一技术细节。

核心问题现象

当开发者尝试在pre-commit的terraform_docs钩子中使用以下功能时：

1. 通过footer-from参数引入外部文件内容
2. 在模板中使用{{ include "file.md" }}语法 常会遇到"no such file or directory"错误，尽管直接运行terraform-docs命令可以正常工作。

问题根源分析

该问题的本质在于pre-commit框架与terraform-docs工具的工作目录差异：

1. pre-commit会基于变更文件所在目录执行钩子
2. terraform-docs默认以项目根目录为工作目录
3. 路径解析策略在两种执行环境下表现不同

解决方案详解

方案一：使用绝对路径配置

在.terraform-docs.yml配置文件中，建议采用项目根目录的相对路径：

formatter: md
footer-from: "docs/footer.md"  # 相对于项目根目录

方案二：统一文件存放位置

最佳实践是将模板文件存放在与Terraform模块同级的目录中：

project-root/
├── modules/
│   └── network/
│       ├── main.tf
│       ├── README.md
│       └── docs/  # 模板文件存放处
│           └── footer.md
└── .terraform-docs.yml

方案三：动态路径处理

对于复杂项目结构，可在pre-commit配置中动态设置路径：

hooks:
  - id: terraform_docs
    args:
      - '--args=--config=${PWD}/.terraform-docs.yml'
      - '--args=--footer-from=${PWD}/docs/footer.md'

配置验证技巧

1. 使用pre-commit run -v查看详细执行路径
2. 在配置中添加verbose: true参数输出调试信息
3. 通过git diff检查生成的文档内容是否符合预期

高级用法建议

1. 多环境支持：为不同环境（dev/prod）配置不同的footer内容
2. 模板组合：将通用内容拆分为多个include文件
3. 版本控制：确保terraform-docs版本与pre-commit插件版本兼容

总结

理解pre-commit框架与terraform-docs工具的工作目录差异是解决此类问题的关键。通过规范化的文件存放位置、明确的路径配置以及充分的测试验证，可以构建稳定可靠的自动化文档生成流程。建议团队在项目初期就建立统一的文档模板规范，避免后期维护成本增加。

对于复杂项目结构，推荐采用方案三的动态路径处理方法，这能提供最大的灵活性。同时记得在CI/CD流水线中保持与本地开发环境一致的文档生成逻辑，确保"一次编写，处处一致"的文档产出效果。