Git使用subtree机制实现第三方分支的敏捷导入与更新-git-PHP中文网

git subtree本质是将另一仓库提交历史按路径重写后线性合并进当前仓库，其核心约束包括：必须用--prefix指定真实存在的子目录路径（不能以/开头或结尾）、历史操作不可逆、push需子仓库写权限。

git使用subtree机制实现第三方分支的敏捷导入与更新

git subtree 不是“导入第三方分支”的快捷键，它本质是把另一个仓库的提交历史（带路径重写）线性合并进当前仓库。所谓“敏捷”，取决于你是否理解它的三个关键约束：必须用 --prefix、历史可选但不可逆、push 依赖子仓库写权限。

因为 subtree 的所有操作都基于路径前缀做提交过滤和重写。没有 --prefix，Git 就不知道你要把哪些提交归为“子项目”、也不知道该从哪个目录开始提取或注入变更。

--prefix=vendor/axios 表示：所有涉及 vendor/axios/ 目录下的文件变更，都视为该子树的修改
这个路径必须真实存在（执行前可为空），且不能以 / 开头或结尾
一旦设定，后续 pull/push/split 都必须复用完全相同的 --prefix 值，否则 Git 无法识别历史归属
如果误设成 --prefix=axios，但实际代码放在 lib/axios 下，后续 pull 会失败并报 “fatal: refusing to merge unrelated histories”

不是网络问题，而是路径、历史或远程配置不一致导致的逻辑拒绝。

Git Pushing

使用约定式提交信息暂存、提交和推送git更改。当用户想要提交和推送更改、提到推送到远程、或要求保存并推送工作时触发。也适用于用户说“推送更改”、“提交并推送”、“推送这个”、“推送到github”或类似git工作流程请求时。

下载

子仓库远程分支已重写历史（如 rebase 或 push --force），而本地没用 --squash，pull 会因找不到共同祖先而中断
主项目中曾手动修改过 --prefix 目录下的文件，但未提交；此时 pull 会提示 “working tree is dirty”，需先 git add -u && git commit 或 git stash
远程别名（如 upstream-lib）被删或 URL 改变，但 pull 命令仍沿用旧名，错误信息为 “fatal: 'upstream-lib' does not appear to be a git repository”

它不是“上传当前目录”，而是从主仓库历史中提取所有匹配 --prefix 的提交，重写路径后打包成新提交，推送到子仓库指定分支。失败往往卡在中间环节。

子仓库目标分支不存在，push 会报 “error: unable to push to unqualified destination” —— 需先在子仓库建好空分支，或改用 git subtree push -P vendor/lib upstream-lib main（确保 main 存在）
主仓库中对子目录的修改未形成独立提交（比如混在大提交里），subtree push 可能漏掉变更，建议始终对子目录修改单独 git commit -m "update vendor/lib"
子仓库有保护分支策略（如 GitHub 的 branch protection），禁止直接推送，需关闭保护或走 PR 流程 —— 此时 push 报 “remote: error: GH006: Protected branch update failed”

它不生成新仓库，只生成一个包含重写路径历史的新分支。很多人以为执行完就万事大吉，其实只是第一步。

git subtree split --prefix=shared/utils --branch=utils-split 后，utils-split 分支只存在于当前仓库，不会自动同步到远程
若要发布为独立库，需另起空目录：git init && git pull ../old-repo utils-split，再 git remote add origin xxx 和 git push -u origin utils-split:main
若原 --prefix 目录下有 gitignore 规则，split 出来的分支默认不带 .gitignore，需手动补上，否则下游 add 时可能漏文件