Git Submodule 子模块

Git Submodule使用

Git项目子模块可以把项目依赖的第三方库拉取过来,方便项目的更新维护和升级.

以下演示在主项目run_s下添加两个子项目acme-client、qiniu-rs的步骤.

主项目:run_s

~/Server/Run/run_s/

$ git config --list
credential.helper=osxkeychain
http.postbuffer=15728640000
user.name=coam
user.email=zyf@lonal.com
core.eol=lf
core.autocrlf=false
core.ignorecase=false
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
core.ignorecase=false
core.precomposeunicode=true
core.eol=lf
core.autocrlf=false
remote.origin.url=git@git.dev.tencent.com:coam/Run.run_s.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*

添加项目子模块src/libs/acme-client:

~/Server/Run/run_s/

$ git submodule add https://github.com/coam/acme-client.git src/libs/acme-client

添加项目子模块src/libs/qiniu-rs:

~/Server/Run/run_s/

$ git submodule add https://github.com/coam/qiniu-rs.git src/libs/qiniu-rs

最后的子模块配置如下:

~/Server/Run/run_s

[coam@MacPro: ~/Server/Run/run_s]$ git config --list
credential.helper=osxkeychain
http.postbuffer=15728640000
user.name=coam
user.email=zyf@lonal.com
core.eol=lf
core.autocrlf=false
core.ignorecase=false
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
core.ignorecase=false
core.precomposeunicode=true
core.eol=lf
core.autocrlf=false
remote.origin.url=git@git.dev.tencent.com:coam/Run.run_s.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
submodule.src/libs/qiniu-rs.url=https://github.com/coam/qiniu-rs.git
submodule.src/libs/qiniu-rs.active=true
submodule.src/libs/acme-client.url=https://github.com/coam/acme-client.git
submodule.src/libs/acme-client.active=true

项目下自动添加的子模块配置:

~/Server/Run/run_s/.gitmodules

[submodule "src/libs/qiniu-rs"]
	path = src/libs/qiniu-rs
	url = https://github.com/coam/qiniu-rs.git
[submodule "src/libs/acme-client"]
	path = src/libs/acme-client
	url = https://github.com/coam/acme-client.git

进入项目下的子模块目录

~/Server/Run/run_s/src/libs/acme-client

$ git config --list
credential.helper=osxkeychain
http.postbuffer=15728640000
user.name=coam
user.email=zyf@lonal.com
core.eol=lf
core.autocrlf=false
core.ignorecase=false
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
core.ignorecase=true
core.precomposeunicode=true
core.worktree=../../../../../src/libs/acme-client
remote.origin.url=https://github.com/coam/acme-client.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.master.remote=origin
branch.master.merge=refs/heads/master

服务端拉取子模块代码

~/Server/Run/run_s/

$ git pull origin master
Fast-forward
 src/libs/acme-client | 1 +
 src/libs/qiniu-rs    | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)
 create mode 160000 src/libs/acme-client

查看git项目子模块配置,发现仅同步下来了子模块文件,并没有配置submodule

~/Server/Run/run_s

$ git config --list
user.email=zyf@lonal.com
user.name=coam
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
remote.origin.url=git@git.dev.tencent.com:coam/Run.run_s.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*

查看项目依赖所有子模块

~/Server/Run/run_s

$ git config --list
user.email=zyf@lonal.com
user.name=coam
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
remote.origin.url=git@git.dev.tencent.com:coam/Run.run_s.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
submodule.src/libs/acme-client.active=true
submodule.src/libs/acme-client.url=https://github.com/coam/acme-client.git
submodule.src/libs/qiniu-rs.active=true
submodule.src/libs/qiniu-rs.url=https://github.com/coam/qiniu-rs.git

子模块代码同步状态

~/Server/Run/run_s

$ git submodule
-04677fdb78227755e43fe817291e9a142bae5b24 src/libs/acme-client
-5026a618754cc5d3b00564553c020d76c328b2d7 src/libs/qiniu-rs

可以看到submodules的状态是hash码和文件目录,但是注意前面有一个减号:-,含义是该子模块代码还没有检出.同步子模块但文件为空同步子模块项目,检出acme-client和qiniu-rs的submodules

~/Server/Run/run_s/

$ git submodule init
Submodule 'src/libs/acme-client' (https://github.com/coam/acme-client.git) registered for path 'src/libs/acme-client'
Submodule 'src/libs/qiniu-rs' (https://github.com/coam/qiniu-rs.git) registered for path 'src/libs/qiniu-rs'
$ git submodule update
Cloning into '/data/home/coam/Server/Run/run_s/src/libs/qiniu-rs'...
Submodule path 'src/libs/acme-client': checked out '04677fdb78227755e43fe817291e9a142bae5b24'
Submodule path 'src/libs/qiniu-rs': checked out '5026a618754cc5d3b00564553c020d76c328b2d7'

再次查看git项目子模块配置

~/Server/Run/run_s

$ git config --list
user.email=zyf@lonal.com
user.name=coam
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
remote.origin.url=git@git.dev.tencent.com:coam/Run.run_s.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
submodule.src/libs/acme-client.active=true
submodule.src/libs/acme-client.url=https://github.com/coam/acme-client.git
submodule.src/libs/qiniu-rs.active=true
submodule.src/libs/qiniu-rs.url=https://github.com/coam/qiniu-rs.git

查看项目依赖子模块配置

~/Server/Run/run_s

$ git submodule
 04677fdb78227755e43fe817291e9a142bae5b24 src/libs/acme-client (acme-client-0.5.3-2-g04677fd)
 5026a618754cc5d3b00564553c020d76c328b2d7 src/libs/qiniu-rs (heads/master)

向上同步子模块

当子模块文件有更新或切换分支时,如果要使用需要在主项目提交

~/Server/Run/run_s

git add sub-module
git commit -m "use sub-module version 1.1"

向下同步子模块

当子模块文件有代码更新需要同步时,在主项目更新拉取子模块

~/Server/Run/run_s

git submodule update

删除项目子模块src/libs/qiniu-rs:

~/Server/Run/run_s

rm -rf src/libs/acme-client
git config --unset submodule.src/libs/acme-client.url
git config --unset submodule.src/libs/acme-client.active

Reference

• git submodule 实用教程

子模块总结

以项目run_s为例

添加子模块

~/Server/Run/run_s

$ git submodule add https://github.com/coam/acme-client.git src/libs/acme-client
$ git submodule add https://github.com/coam/qiniu-rs.git src/libs/qiniu-rs

提交到项目仓库

~/Server/Run/run_s

$ git push origin master

服务器发布及同步子模块

~/Server/Run/run_s

$ git pull origin master
$ git submodule
$ git submodule init
$ git submodule update

已添加的子模块，如何切换到其它分支

背景

项目 ~/Server/Run/ansible 当前有几个 git 依赖的子模块

git submodule status
 8ff4a241477f5f24c718d606a2ee450b370cc47c plays/roles/modules/docker (7.0.2)
 a1b5485abcba58122cfd4335714e25854572457c plays/roles/modules/git (3.0.1-7-ga1b5485)
 95f97f4ade2dd03e152020cdbeb40d099cbb52e5 plays/roles/modules/golang (3.3.0-2-g95f97f4)
 5c19c1e817ccc1e794c8ee2589fcf35d79281b06 plays/roles/modules/nushell (heads/main)

其中有一个子模块 ~/Server/Run/ansible/plays/roles/modules/nushell 做了一些修改，想在不改变原有分支 main 的条件下，将修改提交到新分支 rebuild 下， 然后将依赖该子模块的分支由 main 切换到新分支

先切换一个 rebuild 新分支，将代码修改提交到这个分支

cd plays/roles/modules/nushell
git checkout -b rebuild
git add .
git commit -m "updates"
git push origin rebuild

查看 plays/roles/modules/nushell 提交日志，最后一条 commit id 为 21918379fbd765d55c50872d5f1875c55097a487

$ cd plays/roles/modules/nushell
$ git log
commit 21918379fbd765d55c50872d5f1875c55097a487 (HEAD -> rebuild, origin/rebuild)
Author: coam <zyf@iirii.com>
Date:   Sun May 26 09:54:39 2024 +0800

    rebuild

commit 5c19c1e817ccc1e794c8ee2589fcf35d79281b06 (origin/main, origin/HEAD, main)
Author: Yethal <26117918+Yethal@users.noreply.github.com>
Date:   Wed May 1 11:10:09 2024 +0200

    Support 0.93.0 changes to plugins (#17)

    * Support 0.93.0 changes to plugins

查看子模块状态，子模块 plays/roles/modules/nushell 提示有修改 (heads/rebuild)

git submodule status
 8ff4a241477f5f24c718d606a2ee450b370cc47c plays/roles/modules/docker (7.0.2)
 a1b5485abcba58122cfd4335714e25854572457c plays/roles/modules/git (3.0.1-7-ga1b5485)
 95f97f4ade2dd03e152020cdbeb40d099cbb52e5 plays/roles/modules/golang (3.3.0-2-g95f97f4)
+21918379fbd765d55c50872d5f1875c55097a487 plays/roles/modules/nushell (heads/rebuild)

执行以下命令

先在子模块切换到新建的 rebuild 分支，在根项目下

$ git submodule update --recursive
$ git add .
$ git commit -m "updates"
$ git push

参考 Changing an existing submodule’s branch