Git 子模块

1 概览

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

2 何时使用 submodules

合适的场景:

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

与其使用 submodules,不如使用 subtrees 的场景:

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

  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"
  1. 查看 submodule 提交变更
[status]
	submoduleSummary = true
  1. diff 时可以看到 submodule 的变更项
[diff]
	submodule = log
  1. 命令别名
[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 参考链接

热门相关:恭喜你被逮捕了   重生野性时代   锦乡里   花月颂   重生野性时代