subtree split 是什么
git subtree split 把某个前缀目录的历史单独提取成一条提交链：只保留与目录相关的提交，生成一个独立分支，可用于把目录拆成新仓库，或作为 subtree push 回推的中间产物。它对历史做重建，产出提交的哈希与原历史不同（内容等价、对象不同）。大目录首次执行可能较慢，产出分支先核对再推送。
基本信息
| 语法 | git subtree split --prefix=<目录> [-b <分支>] |
|---|---|
| 结果 | 生成只含该目录历史的提交链 |
| 用途 | 目录独立成仓、检查目录历史、回推中间产物 |
| 哈希 | 重建提交，与原历史哈希不同 |
| 输出 | 不加 -b 时直接打印结果提交哈希 |
| 性能 | 大目录首次执行慢，产出分支可保存复用 |
典型使用场景
- 拆库迁移：把公共目录拆出为独立仓库，保留其提交历史
- 回推前置：subtree push 内部就是 split 后推送，手工先跑可检查产出
- 历史检查：只看该目录曾经的全部提交，便于审计与统计
- 多目标导出：拆分结果推送到镜像或社区仓库
- 供应商模块：把第三方目录整理成干净历史交还上游
- 排错定位：目录历史疑似异常时对比 split 产出
常用示例
常用示例
git subtree split --prefix=libs/common -b split/common # 提取目录历史到独立分支
git log --oneline split/common | head # 检查提交链是否符合预期
git subtree split --prefix=libs/common # 不加 -b 时直接输出结果哈希
git push origin split/common:refs/heads/common-export # 推送到新仓库或导出分支产出要点
| 要点 | 说明 | 注意 |
|---|---|---|
| 提交范围 | 只含触及该目录的提交 | 混杂改动会带上无关历史 |
| 哈希变化 | 重建产生新哈希 | 文档标注新旧对应关系 |
| 路径不存在 | 无法产出 | 先核对 --prefix 拼写与位置 |
| 复用产出 | 分支可重复用于审查与推送 | 重新 split 会再生成一套 |
拆分结果可直接作为新仓库的初始历史；对大型目录首次执行可能较慢。
拆出独立仓库后要继续同步：仍靠 subtree pull/push 流程往返，别指望 split 结果自动跟随。
推送前先本地看 log 与文件清单，确认历史里没有旧路径下的密钥与大文件。