Git 子模块

1 概览

使用 Git 管理源代码，进行子模块操作时，此文可作为参考（Lookup Cheat-Sheet）

2 何时使用 submodules

合适的场景：

1. 子模块代码应独立于其他应用者项目（container/container project）。不依赖，高内聚，同一代码库共享于多个应用者项目。
2. 代码规模大，若其中某个同样大规模的代码模块长时间不需要更新，器皿项目无需每次拉取时都涉及该模块时，应将该模块独立为子模块。方便合作代码贡献者可以选择只初始化一次，之后都不再提取（fetch）该子模块。
3. 子模块与器皿项目应用不同的框架或语言。

与其使用 submodules，不如使用 subtrees 的场景：

1. 需要让某个模块具有子代码的概念，作为一个器件，依附于器皿项目当中，对其做定制化修改，而不用去动器皿项目，只操作器件。同时具备管理一套代码库的简便性。
2. 模块简单，或模块有依赖器皿项目的代码，则不必拆分为单独的项目仓储，避免冗杂的本地/远程引用（ref）管理。所有代码都是一套本地代码。

3 使用技巧及规范

3.1 为仓储添加和配置子模块

# 添加子模块并跟踪名称为 branch_name 的分支，不加 -b 将会对后续子模块的跟踪产生影响
git submodule add -b branch_name URL_to_Git_repo optional_directory_path

3.1.1 一般原则

1. 为子模块设定分支。除了 git submodule add 时使用 -b 参数设定以外，还可以通过修改 .gitmodules 文件更改。

2. 设计好仓储内子模块的存放路径。除了 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 而言

1. remote 使用 submodule.<name>.branch=branch_name 来确认分支名称，若未设置则使用远程仓储设定的默认分支。再通过读取子模块 branch.branch_name.remote=origin 来确认从远程分支获取的地址和 HEAD，默认为 detached HEAD，对应 remotes/origin/HEAD，获取该分支最新提交。
2. 如果本地子模块签出了某个分支，则 HEAD attached 到对应分支，即 branch.branch_name.merge=refs/heads/branch_name。
3. 如果本地子模块当前的 HEAD commit hash 和 submodule.<name>.branch 中的值不一致的话，会导致子模块被 detach HEAD，不再追踪某个分支，而是映射到 submodule.<name>.branch 最新的提交上。以上通常存在两种情况，第一种是 HEAD 和 submodule.<name>.branch 分支本身就不同。第二种是本地子模块的提交落后于 submodule.<name>.branch 最新的提交。通过添加 --merge 参数可以避免 detachment。
4. 如果子模块有本地提交并与远程提交产生了冲突，需要用 --rebase 参数来解决。
5. 子模块内使用 git pull 直接使用的是对应分支的 HEAD，为 branch.branch_name.merge=refs/heads/branch_name。对应上述第2点，和一个签出 branch_name 分支后 HEAD attach 到 heads/branch_name 的子模块的 HEAD 是一致的。

3.5 常用 git 设置（推荐进行配置）

1. 除了直接改 .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"

2. 查看 submodule 提交变更

[status]
	submoduleSummary = true

3. diff 时可以看到 submodule 的变更项

[diff]
	submodule = log

4. 命令别名

[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"

4 参考链接

• 官方链接1
• 官方链接2
• Github个人分享1
• Github个人分享2
• submodules vs subtrees