Git 子模块
1 概览
使用 Git 管理源代码，进行子模块操作时，此文可作为参考（Lookup Cheat-Sheet）
2 何时使用 submodules
合适的场景：
- 子模块代码应独立于其他应用者项目（container/container project）。不依赖，高内聚，同一代码库共享于多个应用者项目。
- 代码规模大，若其中某个同样大规模的代码模块长时间不需要更新，器皿项目无需每次拉取时都涉及该模块时，应将该模块独立为子模块。方便合作代码贡献者可以选择只初始化一次，之后都不再提取（fetch）该子模块。
- 子模块与器皿项目应用不同的框架或语言。
与其使用 submodules，不如使用 subtrees 的场景：
- 需要让某个模块具有子代码的概念，作为一个器件，依附于器皿项目当中，对其做定制化修改，而不用去动器皿项目，只操作器件。同时具备管理一套代码库的简便性。
- 模块简单，或模块有依赖器皿项目的代码，则不必拆分为单独的项目仓储，避免冗杂的本地/远程引用（ref）管理。所有代码都是一套本地代码。
| Submodules | Subtrees |
|---|---|
| 更复杂 (尤其对初学者) | 更简单 |
| 另一个仓储的一个提交引用链接 | 代码提交会合并到器皿项目的提交历史中 |
| 能够单独被访问（存在于中心服务器中的独立仓储） | 去中心化（直接通过器皿项目访问） |
| 需要更多的步骤来操作 | 克隆，拉取，推送都与之前相同（当然也有针对子树的命令） |
| 不占用器皿项目仓储大小 | 直接占用器皿项目仓储容量 |
3 使用技巧及规范
3.1 为仓储添加和配置子模块
# 添加子模块并跟踪名称为 branch_name 的分支，不加 -b 将会对后续子模块的跟踪产生影响
git submodule add -b branch_name URL_to_Git_repo optional_directory_path
3.1.1 一般原则
-
为子模块设定分支。除了
git submodule add时使用-b参数设定以外，还可以通过修改 .gitmodules 文件更改。 -
设计好仓储内子模块的存放路径。除了
git submodule add时通过optional_directory_name设定以外，还可以通过修改 .gitmodules 文件更改。
注：除了直接用文本编辑器修改 .gitmodules 文件以外，还可以通过命令进行修改（参考如下示例）。
# 查看现有的 submodule 属性
git config --file=.gitmodules -l
# 修改 submodule 属性
git config --file=.gitmodules submodule.modulename.branch branch_name
git config --file=.gitmodules submodule.modulename.path path/to/submodule
git config --file=.gitmodules submodule.modulename.url URL_to_Git_repo
3.2 从一个已经设置好子模块的仓储获取子模块
# 克隆仓储时，同时克隆仓储的子模块，相当于进行了子模块的初始化和更新
git clone --recursive URL_to_Git_repo
# 克隆仓储后，初始化并更新子模块，子模块就会引用子模块仓储默认分支下最新一次提交
git submodule update --init
# 子模块设置变更、子模块变更（新增、更名、删除等）
git pull
git submodule sync
git submodule update --init
3.2.1 对子模块仓储直接进行代码编写
# 签出分支，使子模块具备拉取最新修改并直接连通父仓储推送的能力
git submodule foreach "git checkout $(git config -f $toplevel/.gitmodules submodule.$name.branch || echo main)"
# 子模块远程有更新，需要获取。以下命令等同于进入子模块目录执行 `git pull`。如果本地有未提交的修改，均需要合并操作，有冲突无法合并则获取会失败。
git submodule update --remote --merge
# 推送代码到远程分支
git push --recurse-submodules=on-demand
3.2.2 不更改子模块代码
使用 detached HEAD，子模块链接的是提交 commit 的哈希值 hash。无法拉取或提交代码，只能通过更新仓储的子模块版本，再通过 git submodule update 命令更新子模块。
3.3 删除已有子模块
# 从 .git/config 中删除子模块
git submodule deinit -f path/to/submodule
# 从器皿项目（父项目）的 .git/modules 目录中删除子模块文件夹
rm -rf .git/modules/path/to/submodule
# 从 .gitmodules 中去掉子模块入口并删除子模块所在物理路径 path/to/submodule 下的所有文件
git rm -f path/to/submodule
3.4 常用命令解析
# 为所有子模块执行 git 命令，-q 参数静默模式，--recursive 循环操作所有子模块（包括子模块的子模块引用）
git submodule foreach "git command"
# 更新子模块
# --remote 从子模块远程分支更新（最新），不加此参数则从父仓储的子模块版本链接更新（对应提交哈希值）
# --recursive 循环操作所有子模块（包括子模块的子模块引用）
# --merge，合并远程分支的修改，有冲突需要解决冲突。不会 detach HEAD。
# --rebase，撤销本地提交，临时保存并保留本地修改，应用远程修改，再将本地修改合并，合并时同样需要解决冲突。不会 detach HEAD。
git submodule update
注：对于 --remote 而言
- remote 使用
submodule.<name>.branch=branch_name来确认分支名称，若未设置则使用远程仓储设定的默认分支。再通过读取子模块branch.branch_name.remote=origin来确认从远程分支获取的地址和 HEAD，默认为 detached HEAD，对应remotes/origin/HEAD，获取该分支最新提交。- 如果本地子模块签出了某个分支，则 HEAD attached 到对应分支，即
branch.branch_name.merge=refs/heads/branch_name。- 如果本地子模块当前的 HEAD commit hash 和
submodule.<name>.branch中的值不一致的话，会导致子模块被 detach HEAD，不再追踪某个分支，而是映射到submodule.<name>.branch最新的提交上。以上通常存在两种情况，第一种是 HEAD 和submodule.<name>.branch分支本身就不同。第二种是本地子模块的提交落后于submodule.<name>.branch最新的提交。通过添加 --merge 参数可以避免 detachment。- 如果子模块有本地提交并与远程提交产生了冲突，需要用 --rebase 参数来解决。
- 子模块内使用
git pull直接使用的是对应分支的 HEAD，为branch.branch_name.merge=refs/heads/branch_name。对应上述第2点，和一个签出 branch_name 分支后 HEAD attach 到 heads/branch_name 的子模块的 HEAD 是一致的。
3.5 常用 git 设置（推荐进行配置）
- 除了直接改 .gitconfig 文件，还可通过命令查看和更改
# 查看现有 git 设置
git config --global -l
# 修改现有 git 设置
git config --global status.submoduleSummary true
git config --global diff.submodule log
git config --global alias.spush "push --recurse-submodules=on-demand"
- 查看 submodule 提交变更
[status]
submoduleSummary = true
- diff 时可以看到 submodule 的变更项
[diff]
submodule = log
- 命令别名
[alias]
sdiff = "!git diff && git submodule foreach 'git diff'"
spull = "!git pull && git submodule sync && git submodule update --init"
smerge = "submodule update --remote --merge"
srebase = "submodule update --remote --rebase"
scheckout = "submodule foreach 'git checkout $(git config -f $toplevel/.gitmodules submodule.$name.branch || echo main) && git pull'"
spush = "push --recurse-submodules=on-demand"
