git subtree add 是什么
把外部仓库内容合并到当前仓库的指定前缀目录：子树是普通目录内容，克隆方无需额外命令即可构建。带 --squash 可只保留一次压缩提交，减少历史噪声；不带则带入对方完整历史。
基本信息
| 语法 | git subtree add --prefix=<目录> <远程> <分支> [--squash] |
|---|---|
| 产物 | 目录内容加一次合并（或 squash 提交） |
| 前提 | 远程已 fetch 到本地引用 |
| 更新 | git subtree pull 带同样 prefix |
| 回推 | git subtree push 可把本地改动送回上游 |
| 注意事项 | add 只负责引入；更新用 pull，回推用 push |
| 仓库体积 | 带完整历史引入会增大仓库，--squash 可控制 |
典型使用场景
- 引入共享库：把公共库代码并入仓库方便统一构建。
- 减少依赖管理：小库直接内联，避免包管理器复杂度。
- 文档迁移：外部文档仓库合并进 docs/ 前缀。
- 克隆友好：使用者无需子模块操作即可构建。
- 历史控制：--squash 保持主仓库历史简洁。
- 反向贡献：用 subtree push 把本地修改回推上游。
- 版本发布：内联库随主仓库统一走测试与发布流程。
- 合规审计：第三方代码并入后可纳入统一扫描与许可证检查。
- 教学说明：向团队解释克隆方无需任何特殊操作的原因。
常用示例
常用示例
git remote add vendor https://example.com/libs/common.git
git fetch vendor
git subtree add --prefix=libs/common vendor main --squash # 引入并压成一次提交
git subtree pull --prefix=libs/common vendor main --squash # 后续更新
# git subtree push --prefix=libs/common vendor main # 回推本地修改子树与子模块对比
| 维度 | subtree | submodule |
|---|---|---|
| 使用门槛 | 普通目录，克隆即可用 | 需要 init/update |
| 历史 | 并入或压缩进主仓库 | 保留独立仓库 |
| 更新 | subtree pull | update 指针 |
| 适用 | 共享库、文档 | 独立发布组件 |
| 更新频率 | 手动按批 pull | 需约定节奏，否则长期落后 |
子树是普通目录内容，克隆方无需额外命令；但更新与回推必须记住 prefix，命令写错会重复合并或推错位置。；引入时记录来源与版本，便于日后核对上游变化。