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修改的部分了。