Git Subtree 使用指南

概述

Git subtree 是一个强大的工具，允许您将外部仓库作为子目录嵌入到主项目中，同时保持两个仓库的独立性。与 git submodule 不同，subtree 会将外部代码完全复制到主仓库中，使得克隆和分发更加简单。

主要优势

• 简单分发：克隆主仓库时自动包含所有子项目代码
• 独立开发：子项目可以独立开发和维护
• 双向同步：支持从主项目向子项目推送更改
• 无依赖：不需要特殊的 git 配置或额外的工具

基本命令

1. 添加子树 (Add Subtree)

将外部仓库添加为子树：

git subtree add --prefix=<本地路径> <远程仓库URL> <分支名> --squash

示例：

git subtree add --prefix=Platform/Components/RTOS/OS_Lib ssh://git@192.168.21.7:222/RTOS/rt-thread.git master --squash

参数说明：

• --prefix=<本地路径>：指定子树在主项目中的路径
• --squash：将子项目的所有提交合并为一个提交（推荐）

2. 拉取更新 (Pull)

从远程子树仓库拉取最新更改：

git subtree pull --prefix=<本地路径> <远程仓库URL> <分支名> --squash

示例：

git subtree pull --prefix=Platform/Components/RTOS/OS_Lib ssh://git@192.168.21.7:222/RTOS/rt-thread.git master --squash

3. 推送更改 (Push)

将主项目中对子树的更改推送到远程子树仓库：

git subtree push --prefix=<本地路径> <远程仓库URL> <分支名>

示例：

git subtree push --prefix=Platform/Components/RTOS/OS_Lib ssh://git@192.168.21.7:222/RTOS/rt-thread.git master

4. 分离子树 (Split)

将子树从主项目中分离出来，创建独立的提交历史：

git subtree split --prefix=<本地路径> -b <新分支名>

示例：

git subtree split --prefix=Platform/Components/RTOS/OS_Lib -b rt-thread-split

常用工作流程

场景1：首次添加外部项目

# 1. 添加子树
git subtree add --prefix=external/project ssh://git@server.com/repo.git master --squash

# 2. 提交更改
git commit -m "Add external project as subtree"

场景2：更新外部项目

# 1. 拉取最新更改
git subtree pull --prefix=external/project ssh://git@server.com/repo.git master --squash

# 2. 解决可能的冲突
# 3. 提交合并结果
git commit -m "Update external project"

场景3：向外部项目贡献代码

# 1. 在主项目中修改子树代码
# 2. 提交更改
git add external/project/
git commit -m "Modify external project"

# 3. 推送到外部项目
git subtree push --prefix=external/project ssh://git@server.com/repo.git master

最佳实践

1. 使用 --squash 选项

推荐使用：

git subtree add --prefix=path repo.git master --squash
git subtree pull --prefix=path repo.git master --squash

优势：

• 保持主项目历史清洁
• 避免外部项目的详细提交历史污染主项目
• 更容易追踪和管理

2. 路径命名规范

# 推荐的路径结构
Platform/Components/RTOS/OS_Lib    # 平台组件
external/third-party-lib          # 第三方库
vendor/proprietary-code          # 供应商代码

3. 提交信息规范

# 添加子树
git commit -m "Add RT-Thread OS as subtree"

# 更新子树
git commit -m "Update RT-Thread OS to v4.1.0"

# 修改子树
git commit -m "Modify RT-Thread configuration for our platform"

常见问题与解决方案

问题1：–prefix 选项错误

错误命令：

git subtree push --prefix= ./Platform/Components/RTOS/OS_Lib repo.git master

错误原因：

• 等号后面有空格
• 路径前有多余的 ./

正确命令：

git subtree push --prefix=Platform/Components/RTOS/OS_Lib repo.git master

问题2：推送权限问题

错误信息：

fatal: could not read Username for 'https://github.com': terminal prompts disabled

解决方案：

# 使用 SSH 而不是 HTTPS
git subtree push --prefix=path git@github.com:user/repo.git master

# 或者配置 Git 凭据
git config --global credential.helper store

问题3：合并冲突

处理步骤：

# 1. 拉取时出现冲突
git subtree pull --prefix=path repo.git master --squash

# 2. 解决冲突文件
# 编辑冲突文件，保留需要的更改

# 3. 添加解决后的文件
git add path/

# 4. 完成合并
git commit -m "Resolve subtree merge conflicts"

高级用法

1. 查看子树历史

# 查看子树相关的提交
git log --grep="git-subtree-dir: path"

# 查看特定路径的提交历史
git log --follow -- path/

2. 移除子树

# 1. 删除目录
rm -rf path/

# 2. 提交删除
git add path/
git commit -m "Remove subtree"

# 3. 清理历史（可选）
git filter-branch --tree-filter 'rm -rf path' HEAD

3. 重命名子树路径

# 1. 移动目录
git mv old-path new-path

# 2. 提交重命名
git commit -m "Rename subtree path"

# 3. 更新后续的 subtree 命令使用新路径

与 Git Submodule 的对比

总结

Git subtree 是一个强大的工具，特别适合以下场景：

• 需要将外部项目完全集成到主项目中
• 希望简化项目的分发和部署
• 需要向外部项目贡献代码
• 团队对 git submodule 不熟悉

通过遵循本指南的最佳实践，您可以有效地使用 git subtree 管理项目依赖和外部代码集成。

最后更新：2024年
文档版本：1.0