git submodule 实用教程

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

注册 git 子模块

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

向上同步主仓库

向下同步子模块仓库

疑难杂症

注册 `git`子模块

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

.
└── main.txt

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

.
└── sub.txt

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

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的目录会变成这个样子

.
├── main.txt
└── sub-module
└── sub.txt

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

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

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

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

.
├── main.txt
└── sub-module
└── sub.txt

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

$\color{#df00d0}{第一步}$ ，为sub-module创建一个单独的 git仓库：

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

$\color{#df00d0}{第二步}$ ，从 main-module.git中删除 sub-module文件夹：

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

$\color{#df00d0}{第三步}$ ，将 sub-module.git注册为main-module.git的子模块

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

向下同步子模块仓库

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

git submodule update

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

~/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信息变成了这个样子：

~/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分支，会发生什么呢？

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

~/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强行回去。


~/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，那你不得不在切换分支前把这个子模块卸载掉：

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

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

~/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。

~/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 子模块的原因之一吧。

git submodule 实用教程