git subtree split 生成空提交通常因 --prefix 路径错误：须以斜杠结尾、大小写及历史路径完全匹配，且该目录需在相关提交中真实存在。
git subtree split 为什么只生成空提交
执行 git subtree split 后发现新分支里只有空提交，没文件？大概率是路径写错了，或者没指定正确的 --prefix。
-
--prefix必须以斜杠结尾（如--prefix=src/utils/），否则 Git 会匹配失败，悄悄返回空结果 - 路径区分大小写，且必须完全匹配历史中实际存在的目录结构（比如历史里是
Src/utils/，写成src/utils/就找不到） - 如果该子目录在某些提交中根本不存在（比如早期项目还没建这个目录），
split会跳过那些提交——不是报错，而是静默忽略，容易误以为“没东西”
拆出的子仓库怎么保留原提交历史但不带无关文件
关键不在 split，而在后续的 filter-branch 或 git filter-repo 清理。但注意：git subtree split 本身已经做了“按路径筛选历史”的事，只要 --prefix 对了，出来的就是干净的历史。
- 别用
git subtree push直接推到新远程——它会把整个父仓库的 commit hash 带过去，新仓库里能看到父项目的其他路径，只是内容为空，不干净 - 正确做法：先
git subtree split -P src/lib/ -b lib-only，再git checkout lib-only，然后git remote add origin-new <new-url></new-url>，最后git push origin-new lib-only:main - 如果发现提交里还残留 .gitignore 或 README 的修改记录（但这些文件不在
--prefix下），说明 split 时用了-h（默认行为），改用--rejoin以外的纯切分模式即可
subtree 拆分后如何避免和原仓库冲突
拆完不是终点——后续两边同步才是坑最多的地方。Git 不会自动帮你维护双向关系，所谓“subtree 同步”其实是手动 merge + push 的组合技。
- 往子仓库提交新功能后，想合回主项目？不能直接
git subtree pull，得先git fetch子仓库，再git merge --allow-unrelated-histories（如果历史已彻底分离） - 主项目修改了子目录代码，再
git subtree push到子仓库时，如果子仓库已有新提交，会触发 fast-forward 拒绝——此时必须先git subtree pull拉取子仓库变更，解决冲突后再 push - 最稳的做法：约定子模块只由子仓库维护，主项目只做
pull，禁止在主项目里直接改子目录下的业务逻辑代码
替代方案：git filter-repo 比 subtree split 更干净吗
是的，但代价是重写整个历史。如果你要彻底剥离、不再和原仓库有任何 subtree 关联，git filter-repo 是更彻底的选择。
-
git filter-repo --path src/cli/ --invert-paths是删掉其他路径；而--path src/cli/才是只留这一个路径 - 它会重写所有 commit hash，所以子仓库无法再用
git subtree和原仓库交互——这是优点也是缺点 - 不支持 Windows 默认终端（需 WSL 或 Git Bash），且要求 Python 3.8+；
git subtree原生命令则无此限制 - 如果只是临时拆一个版本发布用，
subtree split足够；如果打算长期独立演进、换 CI、加 OWNERS，直接上filter-repo
真正麻烦的从来不是怎么拆，而是拆完谁来维护同步规则、CI 怎么识别子仓库变更、PR 检查要不要跳过子目录。这些没法靠一条命令解决。
