subtree 的拉取与回推
subtree 的日常维护靠两条命令：subtree pull 把上游仓库的更新拉进前缀目录，subtree push 把本仓库中该目录的提交回推到上游分支。回推本质是 subtree split 后推送，会把目录历史重建为提交链；大型仓库耗时明显，频繁回推说明该考虑换协作方式，例如共享仓库或依赖管理。
基本信息
| 拉取 | git subtree pull --prefix=<目录> <远程> <分支> [--squash] |
|---|---|
| 回推 | git subtree push --prefix=<目录> <远程> <分支> |
| 等价关系 | 回推本质是 split 后推送 |
| 提交粒度 | --squash 把上游更新压成一个提交 |
| 远程约定 | 常用单独 remote 指向上游仓库 |
典型使用场景
- 内嵌公共库：上游修复同步到本地目录
- 本地改进回馈：把本仓库里的目录改动推回上游仓库
- 供应商分支：跟随第三方发布分支又保留本地补丁
- 迁移过渡：fork 与上游保持一致，迁移期双向同步
- 版本发布同步：上游打标签后把该版本合入本地目录
- 只读跟随：只需要拉取上游更新、不打算回馈时，pull 后无需配置推送凭据
常用示例
常用示例
git remote add vendor https://example.com/vendor/common.git # 指向上游
git subtree pull --prefix=libs/common vendor main --squash # 拉取上游更新
git subtree push --prefix=libs/common vendor patch-1 # 回推本目录改动
git log --oneline -5 -- libs/common # 核对目录历史pull 与 push 对照
| 命令 | 方向 | 要点 |
|---|---|---|
| subtree pull | 上游到本地目录 | 建议 --squash 控制历史形态 |
| subtree push | 本地目录到上游 | 重建提交链后推送，耗时随历史增长 |
| subtree split | 中间产物 | 独立历史分支，可检查或导出 |
漏写 --squash 时两侧历史形态不一致，后续 pull 容易冲突频发；团队先统一拉取方式再铺开。
回推目标分支的权限要求常与主仓库不同：先在测试分支验证再推真实分支。
多处镜像：同一上游有主站与镜像时用不同 remote 名分别管理，避免配置互相覆盖。
提交历史整洁度：回推前先把目录内提交整理成有意义的几条，零碎提交推给上游会带来审查负担。