git submodule 实用教程

在这篇文章中,我们来讲解一下 git submodule 的实战用法,包括:

  1. 注册 git 子模块
  2. 从已有的文件创建 git 子模块
  3. 向上同步主仓库
  4. 向下同步子模块仓库
  5. 疑难杂症


注册 git 子模块

假设我们有主仓库 main-module.git,远程地址 https://github.com/bitmingw/main-module.git,目录结构

1
2
.
└── main.txt

以及仓库 sub-module.git,远程地址 https://github.com/bitmingw/sub-module.git,目录结构

1
2
.
└── sub.txt

如果想要将仓库 sub-module.git 注册成为主仓库 main-module.git 的一个子模块,可以使用如下指令:

1
2
3
# main-module/
git submodule add https://github.com/bitmingw/sub-module.git
git commit -m "add submodule version 1.0"

git 会自动从远程服务器 clone sub-module.git,之后 main-module.git 的目录会变成这个样子

1
2
3
4
.
├── main.txt
└── sub-module
└── sub.txt

由于添加 git 子模块的操作本身也是一个提交,因此它仅仅对 main-module.git 的当前分支有效,另外的分支不会感知到这一变化。


从已有的文件创建 git 子模块

大多数时候,git 子模块不是凭空创建的,而是从项目中已有的文件拆分出来的。从已有的文件创建 git 子模块需要做三件事:首先为拆分出来的文件创建新的 git 仓库,然后从主仓库中将独立出去的文件移除,最后再注册 git 子模块。

例如,假设 main-module.git 的目录结构如下所示

1
2
3
4
.
├── main.txt
└── sub-module
└── sub.txt

它有 v1.0v2.0 两个分支,在 v2.0 分支中,我们想让 sub-module 文件夹变成 sub-module.git 子模块。

第一步,为 sub-module 创建一个单独的 git 仓库:

1
2
3
4
5
6
7
git checkout v2.0
cd sub-module
git init
git add sub.txt
git commit -m "version 1.0 of sub-module"
git remote add origin https://github.com/bitmingw/sub-module.git
git push -u origin master

第二步,从 main-module.git 中删除 sub-module 文件夹:

1
2
3
cd ..  # main-module/
git rm -r sub-module
git commit -m "remove sub-module directory"

第三步,将 sub-module.git 注册为 main-module.git 的子模块

1
2
3
# main-module/
git submodule add https://github.com/bitmingw/sub-module.git
git commit -m "add submodule version 1.0"


向上同步主仓库

如果你是子模块的开发者,当你希望主仓库使用新版本的子模块时,需要向上同步主仓库。

在主仓库中,可以使用 git submodule statusgit status 查看子模块的状态。

如果主仓库使用的是最新版本的子模块,会显示如下内容:

1
2
3
4
5
6
7
~/main-module$ git submodule status
359bce6ea04c082229fb009013a4dd14c8af4f0c sub-module (heads/master)

~/main-module$ git status
On branch v2.0
Your branch is up-to-date with 'origin/v2.0
nothing to commit, working directory clean

当子模块有未被使用的新提交时(例如在 sub-module.git 中执行 git pull --rebase 拉取新的内容后),git 会给予提示:

1
2
3
4
5
6
7
8
9
10
11
12
13
~/main-module$ git submodule status
+773275124c59b906da71e892b2f9d53c633bc252 sub-module (heads/master)

~/main-module$ git status
On branch v2.0
Your branch is up-to-date with 'origin/v2.0'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

modified: sub-module (new commits)

no changes added to commit (use "git add" and/or "git commit -a")

此时,如果想要将子模块的内容同步到主仓库,只需要在主仓库中创建一个新的提交即可:

1
2
3
# main-module/
git add sub-module
git commit -m "use sub-module version 1.1"


向下同步子模块仓库

如果你是主仓库的开发者,你可能不想使用最新版本的子模块,而是使用主仓库中指定版本的子模块,此时可以使用下面的指令:

1
git submodule update

在使用该指令前,主仓库和子模块的 git status 分别是:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
~/main-module$ git status
On branch v2.0
Your branch is up-to-date with 'origin/v2.0'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

modified: sub-module (new commits)

no changes added to commit (use "git add" and/or "git commit -a")

========

~/main-module/sub-module$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

使用了 git submodule update 之后,两个仓库的 git status 信息变成了这个样子:

1
2
3
4
5
6
7
8
9
10
~/main-module$ git status
On branch v2.0
Your branch is up-to-date with 'origin/v2.0'.
nothing to commit, working directory clean

========

~/main-module/sub-module$ git status
HEAD detached at 359bce6
nothing to commit, working directory clean

这样,主仓库的开发者就可以从一个干净的空间开始工作了。


疑难杂症

还记得我们是从 v2.0 分支引入子模块的么?假如现在要查看 v1.0 分支,会发生什么呢?

1
2
3
4
5
~/main-module$ git checkout v1.0
error: The following untracked working tree files would be overwritten by checkout:
sub-module/sub.txt
Please move or remove them before you can switch branches.
Aborting

难道有了子模块之后我们就回不去了??情况没有那么糟糕,我们可以通过 git checkout -f v1.0 强行回去。

1
2
3
4
~/main-module$ git checkout -f v1.0
warning: unable to rmdir sub-module: Directory not empty
Switched to branch 'v1.0'
Your branch is up-to-date with 'origin/v1.0'.

不过这个时候要注意,由于 sub-module 没有被移除,因此切换到 v1.0 分支以后,你看到的 sub-module 文件夹依然是个子模块。也就是说,子模块穿越了时空来到了 v1.0 分支…… 嗯这个行为似乎不是我们期望的那个样子。

如果你真的想回到 v1.0 分支的非子模块的 sub-module,那你不得不在切换分支前把这个子模块卸载掉:

1
2
3
git rm -r sub-module
git commit -m "remove submodule"
git checkout v1.0

如果你想从 v1.0 分支回到 v2.0,也会遇到一些问题。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
~/main-module$ git checkout v2.0
M sub-module
Switched to branch 'v2.0'
Your branch is up-to-date with 'origin/v2.0'.

~/main-module$ git status
On branch v2.0
Your branch is up-to-date with 'origin/v2.0'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
(commit or discard the untracked or modified content in submodules)

modified: sub-module (modified content)

no changes added to commit (use "git add" and/or "git commit -a")

经过了 git checkout -f v1.0git checkout v2.0 之后,子模块的文件竟然被 git 删掉了。而且这个时候无论是 git submodule update 还是 git checkout -- sub-module 都不好使了。到底应该怎么办呢?

答案是在子模块内部使用 git reset

1
2
3
4
5
6
~/main-module/sub-module$ git reset --hard HEAD
HEAD is now at 359bce6 version 1.0 of sub-module

~/main-module/sub-module$ git status
HEAD detached at 359bce6
nothing to commit, working directory clean

从这一部分的演示可以看出,git submodule 的设计对从已有文件拆分出来的子模块来说是非常糟糕的。或许这会成为大家尽量避免使用 git 子模块的原因之一吧。