Git 提交规范

Git 提交与版本纪律：原子提交、消息写清"为什么"、主干开发、发布打 tag。含 Windows 下的常见坑与安全推送做法。

Git 提交与版本纪律

结论先行

提交是存档点，不是仪式。 每个能独立解释的改动单独提交；消息写清为什么，不写"update"。

分支活不过三天；主干始终保持可运行。

关键事实

| 项 | 说明 |

| --- | --- |

| 提交粒度 | 一个逻辑改动一个提交，能单独回滚 |

| 消息格式 | type(scope): 说明为什么，如 fix(skills): 绕开 Windows 整包解压失败 |

| 分支寿命 | 1-3 天，超期就拆小或改开关 |

| 发布标记 | git tag v1.2.3 + 变更说明，tag 只打已验证的提交 |

| 仓库入口 | git.zilvxingqiu.top，自动化推送用 deploy 账号 |

步骤

1. 提交前自检

```powershell

git -C <repo> status --short

git -C <repo> diff --stat

node scripts/selfcheck.mjs # 有就必跑

```

检查点：没有误加入的 node_modules、dist、密钥文件。

2. 拆成原子提交

- 一个 bug 修复 + 它的回归测试 = 可以同一条；

- 重构 + 新功能 = 必须拆两条；

- 混在一起时用 git add -p 逐块暂存。

3. 写消息（主题 ≤ 50 字，正文写动机与影响）

```

fix(skills): 引入器改为选择性解压

Windows 上整包解压会因中文/超长路径条目失败，

改为只解 SKILL.md 与 scripts/references。

```

4. 推送并验证

```powershell

git -C <repo> push https://deploy:<token>@git.zilvxingqiu.top/sanshan/sanshan-kaiwu.git main

git -C <repo> ls-remote https://deploy:<token>@git.zilvxingqiu.top/sanshan/sanshan-kaiwu.git refs/heads/main

```

检查点：远端 ref 与本地 HEAD 一致。

5. 发布

```powershell

git -C <repo> tag -a v0.1.0 -m "首个可安装版本"

git -C <repo> push <url> v0.1.0

```

同时生成 RELEASE.md：版本、文件、SHA-256、变更说明。

坑

| 现象 | 原因 | 处理 |

| --- | --- | --- |

| LF will be replaced by CRLF | Windows 换行符转换 | 无害；需要统一就加 .gitattributes |

| 推送后远端没变化 | 推错分支/推错地址 | 用 ls-remote 对比提交号 |

| 提交里混进大文件 | .gitignore 漏了 | git rm --cached 后补规则 |

| 密码写进 remote URL | 图省事 | 用一次性 URL 推送，长期用凭据管理器 |

| 中文路径乱码 | 控制台编码 | 用文件工具读写，不要靠 Get-Content 管道 |

验收清单

• [ ] git status 干净，没有残留未跟踪的大文件
• [ ] 每个提交能独立解释，且能单独 revert
• [ ] 提交消息写清了"为什么"
• [ ] 远端 ref 与本地一致
• [ ] 发布有 tag 与变更说明

别做的事

• 别用 git commit -am "update"；
• 别把密码、token 写进 remote 或提交；
• 别在没验证的提交上打 tag；
• 别长期留一个"开发分支"当回收站。