Git子树（git subtree）非Git内置命令，需Git≥1.7.11且安装git-contrib等配套包；添加时用git subtree add --prefix=路径 --squash，更新用pull，推送修改用push，均需注意路径、远程引用和分支一致性。
Git 子树（git subtree）不是 Git 内置命令，而是作为 git 的子命令脚本存在，需确保 Git 版本 ≥ 1.7.11（推荐 ≥ 2.15），且未被发行版裁剪掉 —— 某些最小化安装的 Linux 发行版（如 Alpine、某些 Docker 镜像）默认不带 git subtree，直接运行会报 git: 'subtree' is not a git command。
确认系统已安装 git-subtree
运行以下命令检查：
git subtree --help
若提示“command not found”，说明缺失。不同发行版安装方式不同：
- Debian/Ubuntu：
sudo apt install git-contrib（注意：不是git主包，git-contrib包含git-subtree脚本） - CentOS/RHEL/Fedora：
sudo dnf install git-all或sudo yum install git-all（git-all是元包，含 contrib 工具） - Arch Linux：
sudo pacman -S git（官方git包已自带git-subtree） - 手动安装（通用）：从 Git 官方 contrib/subtree 复制
git-subtree.sh到$PATH目录（如/usr/local/bin），并加执行权限：chmod +x /usr/local/bin/git-subtree
装完后验证：git subtree --version 应输出版本号。
添加远程子项目为子树（git subtree add）
这是最易出错的一步：路径、远程引用、分支名三者必须对齐，且不能与已有目录冲突。
典型命令格式：
git subtree add --prefix=lib/mylib https://github.com/user/mylib.git main --squash
关键点说明：
-
--prefix必须是**不存在的空目录路径**（如lib/mylib），Git 不会自动创建父级（lib/）；若lib/不存在，先mkdir -p lib -
--squash强烈建议加上：否则会把上游整个历史拉进主项目日志，污染git log，后续git blame和 bisect 都会混乱 - 远程 URL 支持 SSH（
git@github.com:user/repo.git）或 HTTPS，但若用 HTTPS 且启用了 2FA，需配好git credential.helper，否则卡在密码输入 - 分支名（如
main）必须是远程仓库真实存在的分支，拼错会报fatal: Couldn't find remote ref xxx
成功后，git log --oneline 会出现类似这样的提交：
Squashed 'lib/mylib/' content from commit abc1234
更新子树代码（git subtree pull）
更新 ≠ 简单重跑 add。必须使用 pull，否则 Git 无法识别已有子树关系，会报错 fatal: ambiguous argument 'lib/mylib': unknown revision。
正确流程：
- 先确保本地有对应远程别名（如之前用 URL 添加的，可先
git remote add mylib-remote https://github.com/user/mylib.git） - 再执行：
git subtree pull --prefix=lib/mylib mylib-remote main --squash
- 若提示
Already up to date但你知道上游有新提交，可能是本地远程跟踪分支过期了，先git fetch mylib-remote再pull
注意：git subtree pull 默认合并策略是 recursive，如果子树目录下你本地有未提交修改，会触发冲突 —— 这是设计行为，不是 bug。解决方式：要么先 git stash，要么先 commit 你的变更（见下一节）。
向子项目上游推送本地修改（git subtree push）
这是最常被误解的操作。你不能直接 git push 子目录，必须用 subtree push 提取并重构提交历史。
前提条件：
- 你对子树目录（如
lib/mylib/）的修改**必须已提交到主项目**（即出现在git log中） - 远程子项目仓库需有写权限（SSH key 或 token 配置正确）
- 推送目标分支（如
main）必须存在且可写
命令示例：
git subtree push --prefix=lib/mylib mylib-remote main
执行过程：
- Git 会扫描所有涉及
lib/mylib/的提交，按时间顺序提取出文件变更 - 将这些变更打包成一个新提交（或多个，取决于是否加
--rejoin），推送到mylib-remote/main - 若上游已有你没拉取的新提交，会拒绝推送（fast-forward only），此时必须先
pull再push
⚠️ 重要限制：该操作**不会保留原始提交作者信息和时间戳**（除非加 --preserve-commit-hashes，但仅限部分 Git 版本支持）。如果你需要完整保真反向移植，应改用 git format-patch + 手动 git am。
子树管理真正的复杂点不在命令本身，而在于「谁改了什么、能不能推回去、要不要保留历史」这三者的边界判断 —— 每次 git subtree push 前，务必 git log --oneline -- lib/mylib/ 确认待推送的提交范围，避免误推配置性修改或调试代码。
