Git submodule 使用中的常见问题与陷阱

一. 为什么要使用submodule?

面对比较复杂的项目，我们有可能会将代码根据功能拆解成不同的子模块。主项目对子模块有依赖关系，却又并不关心子模块的内部开发流程细节。这种情况下，可以使用git 的submodule来建立当前项目和子项目的依赖关系。

二. submodule的操作

2.1 submodule的创建

通过 git submodule add <submodule_url> 可以创建一个submodule，也可以通过其他git图形化工具便捷创建。

创建成功后，会多出一个包含了子模块的相关信息的.gitmodules 文件，同时会把子模块下载到当前目录中。

2.2 submodule的拉取

有三种方式更新项目内的submodule：

1. 主项目的 fetch ，pull 操作不会更新到子模块，所以我们可以在这些操作后面加上 --recurse-submodules， 这样就可以同步到子模块。
2. 当然最简单的还是切到子模块的目录下，通过正常的拉取操作就ok。
3. 在主项目中直接通过 git submodule update 来更新子模块的代码。

2.3 submodule 的提交

最好直接到子模块的目录下，按照正常的git操作对子模块进行正常的提交流程。

三. 重头戏：submodule的坑

3.1 submodule游离态分支下的提交丢失

如果主工程中进行git submodule update操作 ，会把子模块的当前分支切换成游离态 "Detached Head"，而非任何已有的分支！例如下图中的分支名称为游离态的的@72b2861 这种格式.

很多时候我们没有切换过分支，会在没注意的情况下把修改提交到了这个游离态分支上。然后如果切了master(或者其他已有的)分支后，这个游离态分支和本次的commit都消失不见了，特别是用的图形化git工具(如github客户端，sourcetree等)，没法找到这个游离态分支了。

这个时候可能大家有点慌了，我的提交怎么被遁入虚空了？我一天的心血白费了？
但是你先别慌，要相信git的强大和可靠性。我们既然提交了那么就一定有记录，只要我们找到并且恢复就没事。

解决方案1：

当前分支如果还是游离态分支，可以查看当前提交的commit的change-id，然后到正常的分支上cherry-pick这个commit即可。具体操作如下：

1. 用 git checkout master 将 HEAD 从游离状态切换到 master 分支 , 这时候，git 会报 Warning 说有一个提交没有在 branch 上，记住这个提交的 change-id（假如 change-id 为 aaaa)；
2. 用 git cherry-pick aaaa 来将刚刚的提交作用在 master 分支上；
3. 用 git push 将更新提交到远程版本库中；

命令行操作记录如下：

➜ ui_common git:(df697f9) git checkout master
Warning: you are leaving 1 commit behind, not connected to
any of your branches:

  df697f9 forget to check out master

If you want to keep them by creating a new branch, this may be a good time
to do so with:

 git branch new_branch_name df697f911e5a0f09d883f8f360977e470c53d81e

Switched to branch 'master'
➜ ui_common git:(master) git cherry-pick df697f9

解决方案2：

如果使用图形化git工具，有些在切换分支到其他分支时没有方案1里面提示的warning(例如github客户端)，所以切到其他分支后就不知道commit的change-id。
在这种情况下，我们只需要再回到游离态分支，然后查看提交的记录就ok了。

1. 首先通过在主工程中进行git submodule update操作，把当前分支重置到游离态分支；
2. 使用git log 或图形化工具查看commit列表，找到丢失的commit，万事大吉！
3. 万事大吉个屁，我发现git log里面根本没有我们丢失的commit记录。我知道你很慌，但是先别慌。因为我知道git还有另外一个更详尽的git操作记录：git reflog，我们在reflog中再找找。
4. 果然我们在git reflog中可以找到丢失的commit，在master分支中cherry-pick这个提交，万事大吉！

解决方案2的手把手图形化工具教程

如果是git命令行老手，使用命令行工具可以很快处理submodule的commit丢失问题。
但是如果是不会使用git命令行的新手，可以按照下面的流程，手把手教你恢复。下面是恢复流程：

1. 安装毫无争议的世界第一的git工具：tortoisegit（小乌龟），后面的流程是基于此工具的。安装流程略过；

2. 在主项目目录中使用submodule update，可以再次把子模块重置回游离态。
   

   

   image.png

3. 转到子模块的目录，打开RefLog弹窗。

   
   
   

   image.png

4. 在RefLog目录应该可以看到自己提交的不见的commit了！

   
   
   

   image.png

5. 到这里我们便知道了丢失的commit的change-id，最方便的还是使用git命令行直接cherry-pick丢失的commit，然后后面的流程就可以忽略了，万事大吉！
   但如果不会使用git命令行，就接着往下看吧。
   因为tortoisegit工具的cherrypick功能只能从已有分支中选择，无法找到游离态的分支，所以我们可以通过创建一个分支的方法来曲线救国。

6. 右键这个commit，从丢失的commit创建一个分支TestA;

   
   
   

   image.png

7. 切换到master分支，打开Git Show Log.

   
   
   

   image.png

8. 在git log界面把界面显示的分支切到TestA，然后将丢失的commit cherry-pick到master分支就可以了！

   
   
   

   image.png

9. 上传前记得把临时的TestA分支删掉，万事大吉！

四. 参考链接

唐巧的博客：Git submodule的坑