Git Submodule的使用说明

愿得一心人,白首不相离

——《白头吟》汉/卓文君

解释

Submodule 是一个多项目管理工具,它允许将子项目以独立的 git 项目添加到主项目,而主项目以 submodule 的形式拥有子项目。子项目拥有自己的 commit、push、pull,而与主项目互不干扰。主项目只需要记录子项目的地址和所需要的 commit id,通过地址和 commit id 就能够得到对应的子项目。

[常用情景] 在我们的项目中调用轮子且希望两者解藕,可以分别进行版本管理。

添加

1
2
3
4
5
/*
url: 子项目远程地址或本地地址
path: 子项目路径,可省略
*/
git submodule add [url] [path]

可以看到多了文件: .gitmodules,.gitmodules 储存了 submodule 的路径及远程地址。对改变进行提交。

1
2
git add
git commit -m "xxx"

克隆

在clone带有submodules的项目时,正常clone主项目地址不会拉取submodules,可以使用如下命令同时clone主项目和依赖模块:

1
git clone --recurse-submodules [url]

更新

因为我们的目的是解藕主项目对依赖项目的关联,我在主项目中设置git不跟踪submodules,此时对submodules的更新不会提交到依赖项目中。

在使用中发现依赖项目中存在错误时,切换进submodules自己独立的仓库进行修改和PR,非 submodule 的开发人员就不用关心 submodule 是否更新。

删除

1
2
3
4
5
6
7
8
9
10
11
12
13
# 逆初始化模块,submodule为子模块目录,执行后可发现子模块目录被清空
git submodule deinit [submodule_name]

# 执行如下命令还能看到子项目信息
git submodule

# 删除.gitmodules中记录的模块信息(--cached选项清除.git/modules中的缓存)
git rm --cached test2sub
# 执行如下命令已看看不到删除的子项目信息了
git submodule

# 提交修改
git commit -m "xxx"

P.S.

  • 使用GitHub Action进行自动部署的时候需要对submodules进行额外的配置
  • ↑所以我一般将更新频率慢(固定)的submodules融入自己的项目,以较低代价防止奇奇怪怪的事情发生

Reference

  1. https://gist.github.com/myusuf3/7f645819ded92bda6677