📚 课程目录第3章 Git仓库初始化

3. Git 仓库初始化：创建 Git 仓库、配置 .gitignore、初始化 README 与 LICENSE

Git 仓库是 Terraform 模块的版本控制与协作基础。一个规范初始化的仓库，不仅能够记录模块的每一次变更，还能通过 .gitignore 过滤掉本地敏感文件与编译产物，通过 README 降低团队理解成本，通过 LICENSE 明确代码的使用边界。本节将按照“创建→过滤→说明→授权”的顺序，完成仓库的标准化初始化。

3.1 创建 Git 仓库

推荐在模块根目录执行以下命令，完成本地仓库的初始化：

# 进入模块目录（以 terraform-aws-vpc 为例）
cd terraform-aws-vpc

# 初始化 Git 仓库
git init

# 添加初始文件并完成首次提交
git add .
git commit -m "chore: initial commit for terraform-aws-vpc module"

初始化完成后，建议立即在远程平台（GitHub / GitLab / Bitbucket）创建同名空仓库，并将本地仓库推送至远程：

git remote add origin git@github.com:your-org/terraform-aws-vpc.git
git branch -M main
git push -u origin main

分支策略建议： 模块仓库默认使用 main 作为主分支。后续可通过 release/* 或语义化标签（如 v1.0.0）管理模块版本，避免在 main 上直接进行破坏性变更。

3.2 配置 .gitignore

Terraform 模块在运行 terraform init、terraform plan、terraform apply 时会产生大量本地临时文件。这些文件不应被纳入版本控制，否则会导致仓库臃肿、敏感信息泄露以及跨平台冲突。

以下是一个针对 Terraform 模块的标准 .gitignore 模板：

# === Terraform 本地文件 ===
.terraform/
*.tfstate
*.tfstate.*
crash.log
crash.*.log

# === 敏感变量文件 ===
*.tfvars
*.tfvars.json
override.tf
override.tf.json
*_override.tf
*_override.tf.json

# === 本地 IDE / 系统文件 ===
.idea/
.vscode/
*.swp
*.swo
*~
.DS_Store
Thumbs.db

# === 模块测试临时文件 ===
examples/*/.terraform/
examples/*/terraform.tfstate*
examples/*/crash.log

匹配模式	过滤目标	说明
`.terraform/`	Provider 插件缓存目录	每次 `terraform init` 重新下载，无需提交
`.tfstate`	状态文件及备份	包含明文敏感信息，必须排除
`*.tfvars`	变量赋值文件	可能包含密钥、密码等凭据
`override.tf`	本地覆盖配置	用于开发调试，不应影响其他协作者
`.idea/ .vscode/`	IDE 项目配置	避免编辑器偏好污染仓库

安全红线： 不要提交 .tfvars 文件。如果模块需要提供变量示例，请使用 terraform.tfvars.example 并加入 .gitignore 排除真实文件。一旦凭据被推送到远程仓库，即使后续删除，历史记录中仍可被恢复。

3.3 初始化 README

README 是模块仓库的“门面”。一个结构清晰的 README 能帮助使用者快速判断模块是否满足需求，并降低集成成本。Terraform Registry 和 GitHub 都会自动渲染仓库根目录下的 README.md。

推荐的服务目录模块 README 模板包含以下章节：

模块名称与徽章 — 模块用途一句话概括，附带 Terraform 版本、许可证、CI 状态徽章。
功能特性 — 用列表说明模块解决了哪些问题，例如“支持多可用区部署”、“内置安全组规则”等。
前置条件 — 依赖的 Terraform 版本、Provider 版本、外部资源（如已有 VPC、子网）。
快速开始 — 一个最小可用的 main.tf 调用示例，包含 provider 配置和 module 块。
输入变量 — 使用表格列出所有变量名、类型、默认值、描述。
输出值 — 使用表格列出所有输出名、描述、敏感标记。
资源清单 — 简要说明模块会创建哪些核心资源。
贡献指南 — 如何提 Issue、提交 PR、运行测试。

  最佳实践： 使用 terraform-docs 工具自动从代码注释生成变量和输出表格，避免手动维护 README 与代码不一致。在 CI 中集成 terraform-docs markdown table --output-file README.md . 可保持文档始终同步。

3.4 初始化 LICENSE

许可证决定了其他团队能否使用、修改、分发你的模块。对于企业内部服务目录，通常使用 Apache 2.0 或 MIT；对于需要保护商业利益的模块，可使用 BUSL-1.1 或自定义内部许可证。

许可证	适用场景	核心要求
MIT	完全开放，允许商用、修改、再授权	保留版权声明和许可声明
Apache 2.0	企业级开源，包含专利授权	保留版权声明，修改文件需注明变更
BUSL-1.1	源代码可用，但商用需授权	非生产用途免费，生产需购买许可
UNLICENSED	内部私有模块，不对外公开	无授权，保留所有权利

在仓库根目录创建 LICENSE 文件（无扩展名），将所选许可证的全文粘贴进去。对于企业内部服务目录，建议在 LICENSE 文件头部额外添加一行注释，注明所属组织与生效日期：

Copyright (c) 2025 Your Company Name. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

...（许可证全文）

3.5 初始化流程总览

下图展示了从空目录到标准化仓库的完整初始化流程，包含四个核心步骤及其产出物：

3.6 初始化后的验证检查

完成上述步骤后，建议执行以下验证命令，确保仓库状态健康：

# 1. 检查仓库状态，确认没有未跟踪的敏感文件
git status

# 2. 确认 .gitignore 生效（尝试创建临时文件后再次 git status）
touch terraform.tfstate
git status  # 应显示 terraform.tfstate 被忽略

# 3. 检查 README 和 LICENSE 是否存在
ls -la README.md LICENSE

# 4. 查看提交日志
git log --oneline -3

团队协作建议： 在推送远程仓库之前，使用 git diff --cached 检查暂存区内容，确保没有误将 .terraform/ 或 *.tfvars 加入版本控制。如果团队使用 Git Hooks，可以在 pre-commit 钩子中自动检查 .tfvars 文件是否被暂存。

至此，Terraform 模块仓库的初始化工作全部完成。一个包含 .gitignore、README.md、LICENSE 的标准化仓库，为后续的服务目录模板共享与复用奠定了坚实的版本控制基础。