编辑“︁Git子树操作”︁（章节）

= Git子树操作 =

'''Git子树操作'''（Git Subtree）是一种将外部代码库作为子目录集成到当前项目中的方法，同时保留完整的版本历史记录。与Git子模块（Git Submodule）不同，子树操作不需要额外的元数据文件（如`.gitmodules`），并且所有内容都保存在主仓库中。这使得子树操作更适合某些协作场景，尤其是在需要频繁修改外部依赖的情况下。

== 介绍 ==
Git子树允许将一个Git仓库作为子目录嵌入到另一个Git仓库中。这种方法的主要优势包括：
* '''历史记录保留'''：子树操作会保留外部仓库的完整提交历史。
* '''简化工作流'''：无需额外的配置或初始化步骤（如子模块的`git submodule init`）。
* '''单仓库管理'''：所有代码和依赖项都在同一个仓库中，便于协作和部署。

子树操作适用于以下场景：
* 需要将一个项目作为依赖项嵌入到另一个项目中，同时保留其历史记录。
* 需要修改外部依赖项，并将更改推送回原始仓库。
* 希望避免子模块的复杂性。

== 基本操作 ==

=== 添加子树 ===
要将外部仓库作为子树添加到当前项目中，可以使用`git subtree add`命令。例如，将`https://github.com/example/repo.git`的`main`分支添加到当前项目的`external/repo`目录：

<syntaxhighlight lang="bash">
git subtree add --prefix=external/repo https://github.com/example/repo.git main --squash
</syntaxhighlight>

参数说明：
* `--prefix`：指定子目录路径。
* `--squash`：将外部仓库的历史记录合并为单个提交（可选）。

=== 更新子树 ===
如果外部仓库有更新，可以通过以下命令拉取更改：

<syntaxhighlight lang="bash">
git subtree pull --prefix=external/repo https://github.com/example/repo.git main --squash
</syntaxhighlight>

=== 推送更改 ===
如果修改了子树中的内容并希望将更改推送回原始仓库：

<syntaxhighlight lang="bash">
git subtree push --prefix=external/repo https://github.com/example/repo.git main
</syntaxhighlight>

== 实际案例 ==

=== 案例：嵌入前端库 ===
假设你正在开发一个Web项目，并希望将React库作为子树嵌入到项目中：

1. 添加React库：
<syntaxhighlight lang="bash">
git subtree add --prefix=lib/react https://github.com/facebook/react.git main --squash
</syntaxhighlight>

2. 更新React库：
<syntaxhighlight lang="bash">
git subtree pull --prefix=lib/react https://github.com/facebook/react.git main --squash
</syntaxhighlight>

3. 修改React代码并推送回原始仓库：
<syntaxhighlight lang="bash">
git subtree push --prefix=lib/react https://github.com/facebook/react.git my-feature-branch
</syntaxhighlight>

=== 案例：多仓库协作 ===
假设团队A和团队B分别开发两个相关项目，团队B需要将团队A的代码作为子树嵌入：

1. 团队B添加团队A的仓库：
<syntaxhighlight lang="bash">
git subtree add --prefix=team-a https://github.com/team-a/project.git main
</syntaxhighlight>

2. 团队B定期同步团队A的更改：
<syntaxhighlight lang="bash">
git subtree pull --prefix=team-a https://github.com/team-a/project.git main
</syntaxhighlight>

== 子树 vs 子模块 ==
子树和子模块各有优缺点：

{| class="wikitable"
|-
! 特性 !! Git子树 !! Git子模块
|-
| 历史记录 || 保留完整历史 || 仅保留引用
|-
| 元数据 || 不需要`.gitmodules` || 需要`.gitmodules`
|-
| 初始化 || 直接嵌入 || 需要`git submodule init`
|-
| 修改推送 || 可直接推送 || 需进入子模块目录操作
|-
| 仓库大小 || 较大（包含所有代码） || 较小（仅存储引用）
|}

== 高级用法 ==

=== 拆分子树 ===
如果需要将子目录拆分为独立的仓库，可以使用`git subtree split`：

<syntaxhighlight lang="bash">
git subtree split --prefix=external/repo --branch=new-branch
</syntaxhighlight>

这会创建一个包含`external/repo`历史的新分支`new-branch`。

=== 合并策略 ===
使用`--squash`可以减少主仓库的提交历史，但会丢失详细变更记录。如果希望保留完整历史，可以省略`--squash`。

== 图表示例 ==
以下是一个子树操作的流程示意图：

<mermaid>
graph LR
    A[主仓库] -->|添加子树| B(外部仓库)
    B --> C[主仓库的子目录]
    C -->|修改并推送| B
    B -->|拉取更新| C
</mermaid>

== 数学表示 ==
子树操作的合并过程可以表示为：

<math>
C_{\text{new}} = C_{\text{main}} \cup C_{\text{subtree}}}
</math>

其中：
* <math>C_{\text{main}}</math> 是主仓库的提交集合。
* <math>C_{\text{subtree}}</math> 是子树仓库的提交集合。

== 总结 ==
Git子树是一种强大的工具，适合需要将外部代码库嵌入到项目中的场景。它简化了依赖管理，同时保留了完整的历史记录。对于初学者，建议从简单的`add`和`pull`操作开始，逐步探索更高级的功能。

[[Category:集成部署]]
[[Category:Git]]
[[Category:Git高级操作]]