git subtree add 后子目录为空，大概率因未加 --squash 且远程分支名错误（如写 master 但实际为 main），或远程仓库私有而本地缺少 ssh/token 权限；--squash 可压缩历史、规避多数匹配与权限问题。
git subtree add 时为什么子目录没代码？
执行 git subtree add --prefix=lib/xxx https://github.com/xxx/yyy.git main 后，lib/xxx 目录为空或报错，大概率是没加 --squash 且远程仓库分支名写错了——比如写了 master 但实际是 main，或者远程仓库根本没该分支。
更隐蔽的问题是：远程仓库存在但未公开（私有），而你本地没配置对应 SSH 密钥或 token 权限，git subtree 会静默失败（不报错但不拉代码）。
- 务必确认远程 URL 可以直接
git clone成功 - 优先用
--squash：它把整个子项目历史压成一个提交，避免主项目历史被污染，也绕过多数权限/分支匹配问题 - 如果必须保留完整历史，先手动
git fetch <remote><branch></branch></remote>确认能拿到 ref，再运行add
pull 更新总提示“Already up to date”，但实际代码没变
这是最常踩的坑：git subtree pull 不是从远程仓库“重新下载”代码，而是基于上次 add 或 pull 时生成的“合并提交”做三方合并。如果中间你手动改过子目录里的文件，Git 会认为“本地有变更”，拒绝自动合并，但又不报冲突，只说“up to date”。
典型触发场景：你改了 vendor/react 里的某个文件，然后想 pull 新版 React —— Git 拒绝覆盖你的修改。
- 安全做法：所有对子树的修改，都走
git subtree push回源仓库，而不是直接编辑子目录 - 紧急修复：先
git stash子目录变更，再pull，最后git stash pop手动解决冲突 - 检查是否真同步了：运行
git log --oneline --simplify-by-decoration --all，看有没有新生成的 subtree 合并提交
push 失败提示 “fatal: ambiguous argument 'xxx': unknown revision”
这个错误说明 git subtree push 在内部执行 split 阶段时，找不到你指定子目录的历史起点。常见原因有两个：
一是你用 --squash 添加的子树，它的历史被压缩成单个提交，split 无法从中提取出“可推回原仓库”的线性历史；二是你后续在子目录里混入了非子树来源的提交（比如手动 git commit 进去），破坏了 subtree 的提交链。
- 只要用了
--squash，就别指望push回源仓库——这是设计限制，不是操作失误 - 要支持双向同步，初始
add必须去掉--squash，且团队所有人得约定：子目录的修改只通过pull/push流程，不直连 commit - 验证能否 split：运行
git subtree split --prefix=lib/xxx --onto=HEAD，如果报同样错误，说明历史已断裂
subtree 和 submodule 到底该选哪个？
别纠结“哪个更好”，看协作链路：如果你的子项目需要被多个主项目复用，且这些主项目之间**不共享维护权**（比如开源库被几十个业务方引用），用 subtree + --squash 是最省心的——克隆即用，无额外命令，更新只需一条 pull。
但如果你和子项目是同一团队，双方都要往里提交代码，且希望历史清晰可追溯（比如 UI 组件库和业务项目共用一套 CI/CD），那就必须放弃 --squash，接受 subtree 的复杂性，或者干脆切回 submodule。
- subtree 的“透明性”是双刃剑：对使用者友好，对维护者苛刻——一旦子目录历史被污染，
split和push就不可逆地失效 - 真正难的不是命令本身，而是团队共识：谁能在子目录里
git commit？谁只能pull？这个边界一旦模糊，几个月后没人能理清提交归属
