git config commit.template 路径错误会导致模板静默失效：项目级须用工作区根目录的相对路径（如.gitmessage），全局级须用绝对路径（如~/.gitmessage）；IDE图形提交绕过模板，仅终端git commit（无-m）触发；变量不自动替换，需prepare-commit-msg钩子实现动态内容；强制规范需commit-msg钩子+CI校验。

git config commit.template 路径写错就完全不生效

模板配置项 commit.template 对路径极其敏感，写错一点都不会报错，只是静默失效。项目级配置必须用**相对于工作区根目录的路径**（比如 .gitmessage），不能写成 .git/.gitmessage —— Git 默认不认 .git/ 下的路径；全局配置则必须是**绝对路径**，比如 ~/.gitmessage 或 /home/you/.gitmessage。

常见错误现象：git commit 打开编辑器后一片空白，或还是旧内容，但 git config commit.template 显示路径正确——大概率是路径语义错了。用 ls -l $(git config commit.template) 实际检查文件是否存在、是否可读。

• 项目级：在仓库根目录执行 git config commit.template .gitmessage，模板文件也得放在同一级
• 全局级：用 git config --global commit.template ~/.gitmessage，确保 ~/.gitmessage 文件存在且有读权限
• 别用环境变量缩写（如 $HOME/.gitmessage），Git 不解析 shell 变量

模板只在 git commit 无 -m 时加载，IDE 提交常被绕过

VS Code、JetBrains 等 IDE 的图形化提交按钮，底层调用的是 git commit -m "xxx" 或通过 libgit2 直接提交，**完全跳过 commit.template**。也就是说，配好了模板，点“√”提交照样没提示、没结构。

真正能触发模板的，只有终端里敲 git commit（不带 -m）这一种方式。如果你依赖 GUI 提交，模板基本形同虚设。

• VS Code 用户：可在设置中关闭 “Git: Enable Smart Commit”，并改用命令面板（Ctrl+Shift+P）运行 “Git: Commit” 手动触发编辑器
• 想强制所有提交走模板？只能靠 prepare-commit-msg 钩子预填充内容，再配合 commit-msg 校验格式
• 注意：钩子脚本必须放在 .git/hooks/prepare-commit-msg，且要有可执行权限（chmod +x）

模板里写 $USER 或 $(date) 不会自动替换

Git 原生命令对模板文件做纯文本加载，不执行任何变量展开或命令替换。你在模板里写 Author: $GIT_AUTHOR_NAME 或 Date: $(date)，最终提交信息里就真会出现这几个字符，不是值。

Pilot Digital Twin Setup

部署一个包含 4 个智能体（agent）的数字孪生平台。在以下情况下使用该技能： 1. 用户希望为物理资产监控与预测性维护等场景搭建数字孪生系统……

下载

要动态内容（比如当前分支名、Jira ID、时间戳），必须用 prepare-commit-msg 钩子处理。它在编辑器打开前被调用，能读取 $1（临时消息文件路径）、$2（来源类型，如 merge、commit）、$3（SHA，用于 amend 场景）。

• 示例钩子片段（写入 .git/hooks/prepare-commit-msg）：

  #!/bin/sh
  if [ -z "$2" ] || [ "$2" = "commit" ]; then
    echo "# Branch: $(git rev-parse --abbrev-ref HEAD)" >> "$1"
    echo "# Time: $(date '+%Y-%m-%d %H:%M')" >> "$1"
  fi

• 钩子不会覆盖你模板里的已有内容，只是追加；如需插入到特定位置，得用 sed -i 替换或插入行
• 团队分发钩子不能靠 git config，得用 lefthook 或自定义 install 脚本同步到每个成员的 .git/hooks/

commit.template 是提示，不是约束；真要 enforce 得靠 commit-msg + CI

哪怕你把模板做得再漂亮、再详细，用户删光重写一行 fix bug，Git 也照收不误。commit.template 本质是降低填写成本的辅助手段，不是校验机制。

想让规范落地，必须两层兜底：

• commit-msg 钩子：在提交前读取 $1（消息文件路径），用正则检查是否以 feat:/fix: 开头、是否有空行分隔 header/body、长度是否超限等，不合规直接退出并报错
• CI 流水线：用 git log -1 --format=%B HEAD 提取最新提交信息，同样跑一遍校验逻辑；本地绕过钩子也没用，PR 合并会被拒绝

最容易被忽略的一点：模板文件和钩子脚本都不进 Git 版本管理（.git/hooks/ 不被跟踪），团队新人 clone 仓库后，这些全得手动 setup 或靠初始化脚本注入。