配置 git commit.template 来统一团队提交信息的格式，是建立 Git 工作流规范的第一步。然而，如果你认为仅靠一个模板文件就能一劳永逸，那可能陷入了一个常见的误区。实际上，这个配置的作用非常基础：它仅在你不使用 -m 参数、通过编辑器进行交互式提交时，将模板内容预填到提交信息编辑器中。它本身不强制执行格式，不校验内容，也无法动态填充日期、作者等变量。
简而言之，git commit.template 只是一个友好的提示工具。要构建一套真正强制的、可执行的提交规范，必须将其与 commit-msg 钩子以及持续集成（CI）流程相结合，形成一套完整的质量防护链。
正确配置模板文件：核心在于路径设置
让 Git 在提交时自动加载模板，听起来简单，但路径配置上的一个小疏忽就可能导致功能静默失效。关键在于理解 Git 寻找模板文件的逻辑。
首先，模板文件是一个纯文本文件，可命名为 .gitmessage 或 .git-commit-template，内容为你期望的提交信息格式。核心步骤是如何告诉 Git 这个文件的位置：
- 项目级配置：如果规范仅应用于当前项目，可将模板文件放在项目根目录。然后在项目根目录执行：
git config commit.template .gitmessage。此处必须使用相对路径（相对于仓库根目录）。一个常见错误是指向.git/.gitmessage，这会导致 Git 无法找到文件，从而配置失败。 - 全局配置：如果希望所有 Git 仓库使用同一模板，可使用全局配置：
git config --global commit.template ~/.gitmessage。这里需使用绝对路径，并确保~/.gitmessage文件存在且当前用户有读取权限。
配置后如何验证？在项目目录下执行一次不带 -m 参数的 git commit。如果编辑器打开后预填了模板内容，则说明成功。若未生效，可运行 git config commit.template 检查输出路径是否正确、文件是否可读。
动态内容填充：模板力所不及，钩子才是解决方案
许多开发者尝试在模板文件中使用 Shell 变量或命令替换，例如：
# Author: $GIT_AUTHOR_NAME # Date: $(date +%Y-%m-%d)
期望提交时能自动替换为当前作者和日期。但结果往往令人失望——提交信息中会原样显示“$GIT_AUTHOR_NAME”等字面字符串。原因在于，Git 处理模板时仅进行简单的文本复制，不会解析其中的 Shell 语法。
那么，如何实现提交信息的动态填充？答案是使用 prepare-commit-msg Git 钩子。这个钩子脚本会在提交信息编辑器启动前被调用，它接收一个包含初始提交信息（如模板内容）的临时文件路径作为参数。你可以在此脚本中编写逻辑，读取环境变量、当前分支名等上下文信息，然后修改该临时文件的内容。
例如，一个简单的钩子可以读取 git config user.name 来替换模板中的占位符。实现步骤：
- 在项目的
.git/hooks/目录下创建名为prepare-commit-msg的文件。 - 为其添加可执行权限：
chmod +x .git/hooks/prepare-commit-msg。 - 在其中编写 Shell 或 Python 脚本，对传入的临时消息文件进行操作。
这引出一个协作中的关键问题：.git/hooks 目录默认不受版本控制。如何确保团队每个成员都能使用相同的钩子？可以借助 lefthook、husky 等工具，或团队约定一个自定义安装脚本，将标准化的钩子文件安装到每个成员的本地仓库中。
构建强制规范：从提示到强制拦截
即便配置了模板和动态填充，仍无法阻止有人清空编辑器，随手写下“fix bug”就提交。模板降低了合规成本，但无法阻止违规行为。要真正强制执行规范，必须建立拦截机制。
这通常需要两层防护：
- 本地拦截（
commit-msg钩子）：这是最直接的一关。创建一个commit-msg钩子，它会在用户编写完提交信息后、创建提交对象前被触发。钩子脚本可以读取最终的提交信息文件，并用正则表达式进行校验。例如，检查首行是否符合“类型(范围): 描述”的约定（如feat(api): add new endpoint）。如果校验失败，脚本以非零状态退出，Git 就会中止本次提交，从而将不规范提交拦在本地。 - 远程兜底（CI 流水线）：本地钩子可以被
git commit --no-verify绕过。因此，在 CI/CD 流水线中加入校验是必不可少的第二道防线。CI 任务可以在构建开始时，运行类似git log -1 --format=%B的命令获取最新提交信息，然后使用commitlint或自定义脚本进行校验。如果校验失败，则标记构建失败，阻止代码合入主干。
最后，一个关键但易被忽略的实践是钩子的管理方式。不建议直接将脚本放在 .git/hooks/ 下，因为难以同步。更好的做法是使用 git config core.hooksPath 命令，将钩子路径指向项目内一个受版本控制的目录（例如 githooks/）。这样，所有团队成员在克隆项目后，都能自动使用同一套钩子脚本。
总结来看，git commit.template 是一个有用的起点，但远非终点。一套健壮的提交规范体系，是模板的“引导”、prepare-commit-msg 钩子的“填充”、commit-msg 钩子的“拦截”以及 CI 的“兜底”共同作用的结果。其中任何一个环节的配置错误（如模板路径不对、钩子无执行权限）或协作断层（如钩子未纳入版本管理），都可能导致整个规范在实际开发中形同虚设。
