Ming's Blog
0%

git submodule 实用教程

Posted on Edited on In Disqus:

在这篇文章中，我们来讲解一下 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.0 和 v2.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 status 和 git 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.0 和 git 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 子模块的原因之一吧。