详解git submodule使用以及注意事项

一、背景

在平时的软件开发过程中常常会有这样的场景，自己负责的某个模块会依赖其他模块或者第三方的library。这时你自己的模块是一个独立的代码仓库，你想要实现这样一种功能，当你从你的模块的代码仓库里把代码拉到本地来的时候，能自动的将你依赖的模块或第三方库都拉到指定的目录当中去。

当然要实现这个功能的方法有很多，比如使用repo之类的工具，又比如如果你使用的是svn作为版本管理工具，那么你可以使用svn的external机制来引用第三方的project。

这里要说的是使用git作为版本管理工具的情况。

二、git submodule

其它的细枝末节就不再赘述了，咱直奔主题。

先来看具体用例：

目前有一个模块A，其代码仓库的地址为：projectA.git， 它需要引用另一个模块B, 其代码仓库的地址为：projectB.git。

假设模块A的本地目录为：projectA

希望引用模块B为模块A的子模块，其在模块A目录下的路径为： projectA/projectB

这里我们通过git 的submodule机制来实现。

比如在命令行里可以直接使用如下命令：

cd projectA
git submodule add projectB.git projectB

注： 这个submodule的 子目录指定时不能以 “/”结尾， 比如上面的命令，就不能写成 projectB/ 这个样子。

就这么简单的一句git命令就可以搞定了，当然这还没完，运行完这个命令之后，在projectA目录执行git status命令，可以看到如下的结果：

这时需要使用git commit命令和git push命令，将添加模块B为模块A的子模块的结果push到模块A的代码仓库里面去。

三、git clone包含子模块的代码仓库

此时，就可以使用git clone命令来抓取模块A的代码仓库，但要同时抓取到子模块的仓库的话，还需要一些方法：

正常的使用git clone命令，然后再使用 git submodule init 和git submodule update来获取子模块

git clone projectA.git
cd projectA
git submodule init
git submodule update

其运行结果如下：

在使用git clone命令时，加上–recurse-submodules或–recursive 这样的递归参数

git clone --recursive projectA.git

其运行结果如下：

四、tortoisegit操作submodule

如果是使用tortoisegit的话，也可以使用图形化界面进行submodule的相关操作，如添加submodule就选择如下图所示的菜单：

添加子模块的界面大概就是下面这个样子：

这里和上面一样“path”一栏不能以”/”结尾。 填写之后，点击OK，就会在主模块的目录下添加对应的子模块。

在clone时也是一样的，它既可以只是clone，然后用上面菜单中，Submodule Update 选项来抓取子模块的内容，也可以在clone时选择递归参数，如下所示：

五、忽略submodule中的修改或新增文件

我们引用第三方的project，大多数情况都是想以“只读”的方式引用，不关心第三方project抓取下来之后是不是被修改，或者是在其目录中添加了untracked的file， 因为我们只是拉取第三方的project，而不会(往往时不能或不允许)对第三方project进行提交。

以上面的模块A和模块B的例子来说，如果模块A和模块B中都有进行修改，其结果可能就是如下这个样子：

这并不是我们想要的结果。一开始的时候我的想法是使用 .gitignore 来忽略submodule的修改，但是无法做到，后来经过一番搜索，终于找到了解决良药。在添加了submodule之后，project的目录下回生成一个.gitmodules文件，这个文件记录了子模块的路径和仓库地址等信息，如下图所示：

我们要做的就是在[submodule “projectB”]中添加一个ignore子项，这个ignore子项可以有上个可选的值，untracked, dirty和all, 它们的意思分别是：

• untracked ：忽略 在子模块B(也就是projectB目录)新添加的，未受版本控制内容
• dirty ： 忽略对projectB目录下受版本控制的内容进行了修改
• all ： 同时忽略untracked和dirty

这里我们先选择dirty(至少先保证不提交对子模块B的任何修改)，其他的可以根据具体需求来进行选择。

添加ignore子项之后的.gitmodules文件的内容如下所示：

然后我们再使用git status查看，可以得到图下结果：

可以看出，之前 “modified: projectB(modified content)” 已经不见了， 此时对修改后的.gitmodules文件进行commit和push， 之后在查看status或做commit时就可以忽略掉对子模块B修改的部分了。