在这篇文章中，我们来讲解一下 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子模块。
，为
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
，从
main-module.git中删除 sub-module文件夹：
cd .. # main-module/
git rm -r sub-module
git commit -m "remove sub-module directory"
，将
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 子模块的原因之一吧。
