Git笔记（35）子模块

小灰灰 2023-07-14 14:00 1阅读 0赞

### Git笔记（35） 子模块 ###

*  1. 多个父项目
 *  2. 开始使用子模块
 *  3. 克隆含有子模块的项目
 *  4. 在包含子模块的项目上工作
 *   *  4.1. 从子模块的远端拉取上游修改
     *  4.2. 从项目远端拉取上游更改
 *  5. 在子模块上工作
 *  6. 发布子模块改动
 *  7. 合并子模块改动
 *  8. 子模的块技巧
 *   *  8.1. 子模块遍历
     *  8.2. 有用的别名
 *  9. 子模块的问题
 *   *  9.1. 切换分支
     *  9.2. 从子目录切换到子模块

--------------------

# 1. 多个父项目 #

有种情况经常会遇到：  
某个工作中的项目需要包含并使用另一个项目

现在问题来了：  
想要把它们当做两个独立的项目，同时又想在一个项目中使用另一个

假设正在开发一个网站然后创建了 Atom 订阅

决定使用一个库，而不是写自己的 Atom 生成代码  
可能不得不通过 CPAN 安装或 Ruby gem 来包含共享库中的代码  
或者将源代码直接拷贝到自己的项目中

如果将这个库包含进来  
那么无论用何种方式都很难定制它，部署则更加困难  
因为必须确保每一个客户端都包含该库

如果将代码复制到自己的项目中  
那么你做的任何自定义修改都会使合并上游的改动变得困难

Git 通过子模块来解决这个问题  
子模块允许将一个 Git 仓库作为另一个 Git 仓库的子目录  
它能让你将另一个仓库克隆到自己的项目中，同时还保持提交的独立

--------------------

# 2. 开始使用子模块 #

将要演示如何在一个被分成一个主项目与几个子项目的项目上开发

首先将一个已存在的 Git 仓库添加为正在工作的仓库的子模块  
可以通过在 `git submodule add` 命令后面加上想要跟踪的项目的相对或绝对 `URL` 来添加新的子模块

在本例中，将会添加一个名为 “`DbConnector`” 的库

$ git submodule add https://github.com/chaconinc/DbConnector
    Cloning into 'DbConnector'...
    remote: Counting objects: 11, done.
    remote: Compressing objects: 100% (10/10), done.
    remote: Total 11 (delta 0), reused 11 (delta 0)
    Unpacking objects: 100% (11/11), done.
    Checking connectivity... done.

默认情况下，子模块会将子项目放到一个与仓库同名的目录中  
如果想要放到其他地方，那么可以在命令结尾添加一个不同的路径

如果这时运行 `git status`，你会注意到几件事

$ git status
    On branch master
    Your branch is up-to-date with 'origin/master'.
    
    Changes to be committed:
      (use "git reset HEAD <file>..." to unstage)
    
    	new file:   .gitmodules
    	new file:   DbConnector

首先应当注意到新的 `.gitmodules` 文件

该配置文件保存了项目 URL 与已经拉取的本地目录之间的映射：

[submodule "DbConnector"]
    	path = DbConnector
    	url = https://github.com/chaconinc/DbConnector

如果有多个子模块，该文件中就会有多条记录  
要重点注意的是，该文件也像 `.gitignore` 文件一样受到（通过）版本控制  
它会和该项目的其他部分一同被拉取推送  
这就是克隆该项目的人知道去哪获得子模块的原因

在 `git status` 输出中列出的另一个是项目文件夹记录  
如果运行 `git diff`，会看到类似下面的信息：

$ git diff --cached DbConnector
    diff --git a/DbConnector b/DbConnector
    new file mode 160000
    index 0000000..c3f01dc
    --- /dev/null
    +++ b/DbConnector
    @@ -0,0 +1 @@
    +Subproject commit c3f01dc8862123d317dd46284b05b6892c7b29bc

虽然 DbConnector 是工作目录中的一个子目录，但 Git 还是会将它视作一个子模块  
当不在那个目录中时，Git 并不会跟踪它的内容  
而是将它看作 **子模块仓库中的某个具体的提交**

如果想看到更漂亮的差异输出，可以给 `git diff` 传递 `--submodule` 选项

$ git diff --cached --submodule
    diff --git a/.gitmodules b/.gitmodules
    new file mode 100644
    index 0000000..71fc376
    --- /dev/null
    +++ b/.gitmodules
    @@ -0,0 +1,3 @@
    +[submodule "DbConnector"]
    +       path = DbConnector
    +       url = https://github.com/chaconinc/DbConnector
    Submodule DbConnector 0000000...c3f01dc (new submodule)

当提交时，会看到类似下面的信息：

$ git commit -am 'added DbConnector module'
    [master fb9093c] added DbConnector module
     2 files changed, 4 insertions(+)
     create mode 100644 .gitmodules
     create mode 160000 DbConnector

注意 DbConnector 记录的 160000 模式  
这是 Git 中的一种特殊模式，它本质上意味着你是**将一次提交记作一项目录记录**的  
而非将它记录成一个子目录或者一个文件

最后，推送这些更改：

$ git push origin master

--------------------

# 3. 克隆含有子模块的项目 #

接下来将会克隆一个含有子模块的项目  
当你在克隆这样的项目时，默认会包含该子模块目录  
但其中还没有任何文件：

$ git clone https://github.com/chaconinc/MainProject
    Cloning into 'MainProject'...
    remote: Counting objects: 14, done.
    remote: Compressing objects: 100% (13/13), done.
    remote: Total 14 (delta 1), reused 13 (delta 0)
    Unpacking objects: 100% (14/14), done.
    Checking connectivity... done.
    $ cd MainProject
    $ ls -la
    total 16
    drwxr-xr-x   9 schacon  staff  306 Sep 17 15:21 .
    drwxr-xr-x   7 schacon  staff  238 Sep 17 15:21 ..
    drwxr-xr-x  13 schacon  staff  442 Sep 17 15:21 .git
    -rw-r--r--   1 schacon  staff   92 Sep 17 15:21 .gitmodules
    drwxr-xr-x   2 schacon  staff   68 Sep 17 15:21 DbConnector
    -rw-r--r--   1 schacon  staff  756 Sep 17 15:21 Makefile
    drwxr-xr-x   3 schacon  staff  102 Sep 17 15:21 includes
    drwxr-xr-x   4 schacon  staff  136 Sep 17 15:21 scripts
    drwxr-xr-x   4 schacon  staff  136 Sep 17 15:21 src
    $ cd DbConnector/
    $ ls
    $

其中有 DbConnector 目录，不过是空的  
必须运行两个命令：  
`git submodule init` 用来初始化本地配置文件  
`git submodule update` 则从该项目中抓取所有数据并检出父项目中列出的合适的提交

$ git submodule init
    Submodule 'DbConnector' (https://github.com/chaconinc/DbConnector) registered for path 'DbConnector'
    $ git submodule update
    Cloning into 'DbConnector'...
    remote: Counting objects: 11, done.
    remote: Compressing objects: 100% (10/10), done.
    remote: Total 11 (delta 0), reused 11 (delta 0)
    Unpacking objects: 100% (11/11), done.
    Checking connectivity... done.
    Submodule path 'DbConnector': checked out 'c3f01dc8862123d317dd46284b05b6892c7b29bc'

现在 DbConnector 子目录是处在和之前提交时相同的状态了

不过还有更简单一点的方式  
如果给 `git clone` 命令传递 `--recurse-submodules` 选项  
它就会自动初始化并更新仓库中的每一个子模块， 包括可能存在的嵌套子模块

$ git clone --recurse-submodules https://github.com/chaconinc/MainProject
    Cloning into 'MainProject'...
    remote: Counting objects: 14, done.
    remote: Compressing objects: 100% (13/13), done.
    remote: Total 14 (delta 1), reused 13 (delta 0)
    Unpacking objects: 100% (14/14), done.
    Checking connectivity... done.
    Submodule 'DbConnector' (https://github.com/chaconinc/DbConnector) registered for path 'DbConnector'
    Cloning into 'DbConnector'...
    remote: Counting objects: 11, done.
    remote: Compressing objects: 100% (10/10), done.
    remote: Total 11 (delta 0), reused 11 (delta 0)
    Unpacking objects: 100% (11/11), done.
    Checking connectivity... done.
    Submodule path 'DbConnector': checked out 'c3f01dc8862123d317dd46284b05b6892c7b29bc'

如果已经克隆了项目但忘记了 `--recurse-submodules`  
那么可以运行 `git submodule update --init` 将两个命令合并成一步  
如果还要初始化、抓取并检出任何嵌套的子模块  
请使用简明的 `git submodule update --init --recursive`

--------------------

# 4. 在包含子模块的项目上工作 #

现在有一份包含子模块的项目副本，将会同时在主项目和子模块项目上与队员协作

--------------------

## 4.1. 从子模块的远端拉取上游修改 ##

在项目中使用子模块的最简模型，就是只使用子项目并不时地获取更新  
而并不在你的检出中进行任何更改

如果想要在子模块中查看新工作  
可以进入到目录中运行 `git fetch` 与 `git merge`，合并上游分支来更新本地代码

$ git fetch
    From https://github.com/chaconinc/DbConnector
       c3f01dc..d0354fc  master     -> origin/master
    $ git merge origin/master
    Updating c3f01dc..d0354fc
    Fast-forward
     scripts/connect.sh | 1 +
     src/db.c           | 1 +
     2 files changed, 2 insertions(+)

如果现在返回到主项目并运行 `git diff --submodule`  
就会看到子模块被更新的同时获得了一个包含新添加提交的列表

如果不想每次运行 `git diff` 时都输入 `--submodle`  
那么可以将 `diff.submodule` 设置为 “`log`” 来将其作为默认行为

$ git config --global diff.submodule log
    $ git diff
    Submodule DbConnector c3f01dc..d0354fc:
      > more efficient db routine
      > better connection routine

如果在此时提交，那么会将子模块锁定为其他人更新时的新代码

如果不想在子目录中手动抓取与合并  
那么还有种更容易的方式  
运行 `git submodule update --remote`，Git 将会进入子模块然后抓取并更新

$ git submodule update --remote DbConnector
    remote: Counting objects: 4, done.
    remote: Compressing objects: 100% (2/2), done.
    remote: Total 4 (delta 2), reused 4 (delta 2)
    Unpacking objects: 100% (4/4), done.
    From https://github.com/chaconinc/DbConnector
       3f19983..d0354fc  master     -> origin/master
    Submodule path 'DbConnector': checked out 'd0354fc054692d3906c85c3af05ddce39a1c0644'

此命令默认会假定你想要更新并检出子模块仓库的 master 分支  
不过也可以设置为想要的其他分支  
例如，想要 DbConnector 子模块跟踪仓库的 “`stable`” 分支  
那么既可以在 `.gitmodules` 文件中设置 （这样其他人也可以跟踪它）  
也可以只在本地的 `.git/config` 文件中设置

让我们在 `.gitmodules` 文件中设置它：

$ git config -f .gitmodules submodule.DbConnector.branch stable
    
    $ git submodule update --remote
    remote: Counting objects: 4, done.
    remote: Compressing objects: 100% (2/2), done.
    remote: Total 4 (delta 2), reused 4 (delta 2)
    Unpacking objects: 100% (4/4), done.
    From https://github.com/chaconinc/DbConnector
       27cf5d3..c87d55d  stable -> origin/stable
    Submodule path 'DbConnector': checked out 'c87d55d4c6d4b05ee34fbc8cb6f7bf4585ae6687'

如果不用 `-f .gitmodules` 选项，那么它只会为你做修改  
但是在仓库中保留跟踪信息更有意义一些，因为其他人也可以得到同样的效果

这时运行 `git status`，Git 会显示子模块中有“新提交”。

$ git status
    On branch master
    Your branch is up-to-date with 'origin/master'.
    
    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:   .gitmodules
      modified:   DbConnector (new commits)
    
    no changes added to commit (use "git add" and/or "git commit -a")

如果设置了配置选项 `status.submodulesummary`，Git 也会显示你的子模块的更改摘要：

$ git config status.submodulesummary 1
    
    $ git status
    On branch master
    Your branch is up-to-date with 'origin/master'.
    
    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:   .gitmodules
    	modified:   DbConnector (new commits)
    
    Submodules changed but not updated:
    
    * DbConnector c3f01dc...c87d55d (4):
      > catch non-null terminated lines

这时如果运行 `git diff`，可以看到我们修改了 `.gitmodules` 文件  
同时还有几个已拉取的提交需要提交到我们自己的子模块项目中

$ git diff
    diff --git a/.gitmodules b/.gitmodules
    index 6fc0b3d..fd1cc29 100644
    --- a/.gitmodules
    +++ b/.gitmodules
    @@ -1,3 +1,4 @@
     [submodule "DbConnector"]
            path = DbConnector
            url = https://github.com/chaconinc/DbConnector
    +       branch = stable
     Submodule DbConnector c3f01dc..c87d55d:
      > catch non-null terminated lines
      > more robust error handling
      > more efficient db routine
      > better connection routine

这非常有趣，因为可以直接看到将要提交到子模块中的提交日志  
提交之后，也可以运行 `git log -p` 查看这个信息

$ git log -p --submodule
    commit 0a24cfc121a8a3c118e0105ae4ae4c00281cf7ae
    Author: Scott Chacon <schacon@gmail.com>
    Date:   Wed Sep 17 16:37:02 2014 +0200
    
        updating DbConnector for bug fixes
    
    diff --git a/.gitmodules b/.gitmodules
    index 6fc0b3d..fd1cc29 100644
    --- a/.gitmodules
    +++ b/.gitmodules
    @@ -1,3 +1,4 @@
     [submodule "DbConnector"]
            path = DbConnector
            url = https://github.com/chaconinc/DbConnector
    +       branch = stable
    Submodule DbConnector c3f01dc..c87d55d:
      > catch non-null terminated lines
      > more robust error handling
      > more efficient db routine
      > better connection routine

当运行 `git submodule update --remote` 时，Git 默认会尝试更新所有子模块  
所以如果有很多子模块的话，可以传递想要更新的子模块的名字

--------------------

## 4.2. 从项目远端拉取上游更改 ##

现在，站在协作者的视角，有自己的 MainProject 仓库的本地克隆  
只是执行 `git pull` 获取你新提交的更改还不够：

$ git pull
    From https://github.com/chaconinc/MainProject
       fb9093c..0a24cfc  master     -> origin/master
    Fetching submodule DbConnector
    From https://github.com/chaconinc/DbConnector
       c3f01dc..c87d55d  stable     -> origin/stable
    Updating fb9093c..0a24cfc
    Fast-forward
     .gitmodules         | 2 +-
     DbConnector         | 2 +-
     2 files changed, 2 insertions(+), 2 deletions(-)
    
    $ git status
     On branch master
    Your branch is up-to-date with 'origin/master'.
    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:   DbConnector (new commits)
    
    Submodules changed but not updated:
    
    * DbConnector c87d55d...c3f01dc (4):
      < catch non-null terminated lines
      < more robust error handling
      < more efficient db routine
      < better connection routine
    
    no changes added to commit (use "git add" and/or "git commit -a")

默认情况下，`git pull` 命令会递归地抓取子模块的更改，如上面第一个命令的输出所示  
然而，**它不会更新子模块**

这点可通过 `git status` 命令看到，它会显示子模块“已修改”，且“有新的提交”  
此外，左边的尖括号（<）指出了新的提交，表示这些提交已在 MainProject 中记录  
但尚未在本地的 DbConnector 中检出

为了完成更新，需要运行 `git submodule update`：

$ git submodule update --init --recursive
    Submodule path 'vendor/plugins/demo': checked out '48679c6302815f6c76f1fe30625d795d9e55fc56'
    
    $ git status
     On branch master
    Your branch is up-to-date with 'origin/master'.
    nothing to commit, working tree clean

请注意，为安全起见  
如果 MainProject 提交了你刚拉取的新子模块  
那么应该在 `git submodule update` 后面添加 `--init` 选项  
如果子模块有嵌套的子模块，则应使用 `--recursive` 选项

如果想自动化此过程，那么可以为 `git pull` 命令添加 `--recurse-submodules` 选项（  
这会让 Git 在拉取后运行 `git submodule update`，将子模块置为正确的状态

此外，如果想让 Git 总是以 `--recurse-submodules` 拉取  
可以将配置选项 `submodule.recurse` 设置为 true  
此选项会让 Git 为所有支持 `--recurse-submodules` 的命令使用该选项（除 clone 以外）

在为父级项目拉取更新时，还会出现一种特殊的情况：  
在拉取的提交中， 可能 `.gitmodules` 文件中记录的子模块的 URL 发生了改变  
比如，若子模块项目改变了它的托管平台，就会发生这种情况  
此时，若父级项目引用的子模块提交不在仓库中本地配置的子模块远端上  
那么执行 `git pull --recurse-submodules` 或 `git submodule update` 就会失败  
为了补救，`git submodule sync` 命令需要：

# 将新的 URL 复制到本地配置中
    $ git submodule sync --recursive
    # 从新 URL 更新子模块
    $ git submodule update --init --recursive

--------------------

# 5. 在子模块上工作 #

很有可能正在使用子模块  
因为你确实想在子模块中编写代码的同时，还想在主项目上编写代码（或者跨子模块工作）  
否则大概只能用简单的依赖管理系统（如 Maven 或 Rubygems）来替代了

现在将通过一个例子来演示如何在子模块与主项目中同时做修改  
以及如何同时提交与发布那些修改

到目前为止，当运行 `git submodule update` 从子模块仓库中抓取修改时  
Git 将会获得这些改动并更新子目录中的文件  
但是会将子仓库留在一个称作“游离的 HEAD”的状态

这意味着没有本地工作分支（例如 “master” ）跟踪改动  
如果没有工作分支跟踪更改，也就意味着即便你将更改提交到了子模块  
这些更改也很可能会在下次运行 `git submodule update` 时丢失

如果你想要在子模块中跟踪这些修改，还需要一些额外的步骤

为了将子模块设置得更容易进入并修改，需要做两件事  
首先，进入每个子模块并检出其相应的工作分支  
接着，若做了更改就需要告诉 Git 它该做什么  
然后运行 `git submodule update --remote` 来从上游拉取新工作

可以选择将它们合并到你的本地工作中，也可以尝试将你的工作变基到新的更改上

首先，让我们进入子模块目录然后检出一个分支。

$ cd DbConnector/
    $ git checkout stable
    Switched to branch 'stable'

然后尝试用 “`merge`” 选项来更新子模块  
为了手动指定它，只需给 `update` 添加 `--merge` 选项即可  
这时我们将会看到服务器上的这个子模块有一个改动并且它被合并了进来

$ cd ..
    $ git submodule update --remote --merge
    remote: Counting objects: 4, done.
    remote: Compressing objects: 100% (2/2), done.
    remote: Total 4 (delta 2), reused 4 (delta 2)
    Unpacking objects: 100% (4/4), done.
    From https://github.com/chaconinc/DbConnector
       c87d55d..92c7337  stable     -> origin/stable
    Updating c87d55d..92c7337
    Fast-forward
     src/main.c | 1 +
     1 file changed, 1 insertion(+)
    Submodule path 'DbConnector': merged in '92c7337b30ef9e0893e758dac2459d07362ab5ea'

如果进入 DbConnector 目录，可以发现新的改动已经合并入本地 `stable` 分支  
现在让我们看看当我们对库做一些本地的改动而同时其他人推送另外一个修改到上游时会发生什么

$ cd DbConnector/
    $ vim src/db.c
    $ git commit -am 'unicode support'
    [stable f906e16] unicode support
     1 file changed, 1 insertion(+)

如果我们现在更新子模块，就会看到当我们在本地做了更改时上游也有一个改动  
需要将它并入本地

$ cd ..
    $ git submodule update --remote --rebase
    First, rewinding head to replay your work on top of it...
    Applying: unicode support
    Submodule path 'DbConnector': rebased into '5d60ef9bbebf5a0c1c1050f242ceeb54ad58da94'

如果忘记 `--rebase` 或 `--merge`，Git 会将子模块更新为服务器上的状态  
并且会将项目重置为一个游离的 HEAD 状态

$ git submodule update --remote
    Submodule path 'DbConnector': checked out '5d60ef9bbebf5a0c1c1050f242ceeb54ad58da94'

即便这真的发生了也不要紧，只需回到目录中再次检出你的分支（即还包含着你的工作的分支）  
然后手动地合并或变基 `origin/stable`（或任何一个你想要的远程分支）就行了

如果你没有提交子模块的改动，那么运行一个子模块更新也不会出现问题，此时 Git 会只抓取更改而并不会覆盖子模块目录中未保存的工作

$ git submodule update --remote
    remote: Counting objects: 4, done.
    remote: Compressing objects: 100% (3/3), done.
    remote: Total 4 (delta 0), reused 4 (delta 0)
    Unpacking objects: 100% (4/4), done.
    From https://github.com/chaconinc/DbConnector
       5d60ef9..c75e92a  stable     -> origin/stable
    error: Your local changes to the following files would be overwritten by checkout:
    	scripts/setup.sh
    Please, commit your changes or stash them before you can switch branches.
    Aborting
    Unable to checkout 'c75e92a2b3855c9e5b66f915308390d9db204aca' in submodule path 'DbConnector'

如果你做了一些与上游改动冲突的改动，当运行更新时 Git 会让你知道

$ git submodule update --remote --merge
    Auto-merging scripts/setup.sh
    CONFLICT (content): Merge conflict in scripts/setup.sh
    Recorded preimage for 'scripts/setup.sh'
    Automatic merge failed; fix conflicts and then commit the result.
    Unable to merge 'c75e92a2b3855c9e5b66f915308390d9db204aca' in submodule path 'DbConnector'

你可以进入子模块目录中然后就像平时那样修复冲突

--------------------

# 6. 发布子模块改动 #

现在我们的子模块目录中有一些改动  
其中有一些是我们通过更新从上游引入的  
而另一些是本地生成的，由于我们还没有推送它们  
所以对任何其他人都不可用

$ git diff
    Submodule DbConnector c87d55d..82d2ad3:
      > Merge from origin/stable
      > updated setup script
      > unicode support
      > remove unnecessary method
      > add new option for conn pooling

如果在主项目中提交并推送但并不推送子模块上的改动，其他尝试检出我们修改的人会遇到麻烦  
因为他们无法得到依赖的子模块改动  
那些改动只存在于我们本地的拷贝中

为了确保这不会发生，可以让 Git 在推送到主项目前检查所有子模块是否已推送  
`git push` 命令接受可以设置为 “`check`” 或 “`on-demand`” 的 `--recurse-submodules` 参数  
如果任何提交的子模块改动没有推送那么 “`check`” 选项会直接使 `push` 操作失败

$ git push --recurse-submodules=check
    The following submodule paths contain changes that can
    not be found on any remote:
      DbConnector
    
    Please try
    
    	git push --recurse-submodules=on-demand
    
    or cd to the path and use
    
    	git push
    
    to push them to a remote.

如你所见，它也给我们了一些有用的建议，指导接下来该如何做

最简单的选项是进入每一个子模块中然后手动推送到远程仓库  
确保它们能被外部访问到，之后再次尝试这次推送

如果你想要对所有推送都执行检查  
那么可以通过设置 `git config push.recurseSubmodules check` 让它成为默认行为

另一个选项是使用 “`on-demand`” 值，它会尝试为你这样做

$ git push --recurse-submodules=on-demand
    Pushing submodule 'DbConnector'
    Counting objects: 9, done.
    Delta compression using up to 8 threads.
    Compressing objects: 100% (8/8), done.
    Writing objects: 100% (9/9), 917 bytes | 0 bytes/s, done.
    Total 9 (delta 3), reused 0 (delta 0)
    To https://github.com/chaconinc/DbConnector
       c75e92a..82d2ad3  stable -> stable
    Counting objects: 2, done.
    Delta compression using up to 8 threads.
    Compressing objects: 100% (2/2), done.
    Writing objects: 100% (2/2), 266 bytes | 0 bytes/s, done.
    Total 2 (delta 1), reused 0 (delta 0)
    To https://github.com/chaconinc/MainProject
       3d6d338..9a377d1  master -> master

如你所见，Git 进入到 DbConnector 模块中然后在推送主项目前推送了它  
如果那个子模块因为某些原因推送失败，主项目也会推送失败  
也可以通过设置 `git config push.recurseSubmodules on-demand` 让它成为默认行为

--------------------

# 7. 合并子模块改动 #

如果你其他人同时改动了一个子模块引用，那么可能会遇到一些问题  
也就是说，如果子模块的历史已经分叉并且在父项目中分别提交到了分叉的分支上  
那么你需要做一些工作来修复它

如果一个提交是另一个的直接祖先（一个快进式合并）  
那么 Git 会简单地选择之后的提交来合并，这样没什么问题

不过，Git 甚至不会尝试去进行一次简单的合并  
如果子模块提交已经分叉且需要合并，那会得到类似下面的信息：

$ git pull
    remote: Counting objects: 2, done.
    remote: Compressing objects: 100% (1/1), done.
    remote: Total 2 (delta 1), reused 2 (delta 1)
    Unpacking objects: 100% (2/2), done.
    From https://github.com/chaconinc/MainProject
       9a377d1..eb974f8  master     -> origin/master
    Fetching submodule DbConnector
    warning: Failed to merge submodule DbConnector (merge following commits not found)
    Auto-merging DbConnector
    CONFLICT (submodule): Merge conflict in DbConnector
    Automatic merge failed; fix conflicts and then commit the result.

所以本质上 Git 在这里指出了子模块历史中的两个分支记录点已经分叉并且需要合并  
它将其解释为 “`merge following commits not found`” （未找到接下来需要合并的提交）  
虽然这有点令人困惑，不过之后我们会解释为什么是这样

为了解决这个问题，你需要弄清楚子模块应该处于哪种状态  
奇怪的是，Git 并不会给你多少能帮你摆脱困境的信息，甚至连两边提交历史中的 SHA-1 值都没有  
幸运的是，这很容易解决  
如果运行 `git diff`，就会得到试图合并的两个分支中记录的提交的 SHA-1 值

$ git diff
    diff --cc DbConnector
    index eb41d76,c771610..0000000
    --- a/DbConnector
    +++ b/DbConnector

所以，在本例中，`eb41d76` 是我们的子模块中大家共有的提交，而 `c771610` 是上游拥有的提交  
如果我们进入子模块目录中，它应该已经在 `eb41d76` 上了，因为合并没有动过它  
如果不是的话，无论什么原因，都可以简单地创建并检出一个指向它的分支

来自另一边的提交的 SHA-1 值比较重要  
它是需要你来合并解决的  
可以尝试直接通过 SHA-1 合并，也可以为它创建一个分支然后尝试合并  
建议后者，哪怕只是为了一个更漂亮的合并提交信息

所以，将会进入子模块目录，基于 `git diff` 的第二个 SHA-1 创建一个分支然后手动合并

$ cd DbConnector
    
    $ git rev-parse HEAD
    eb41d764bccf88be77aced643c13a7fa86714135
    
    $ git branch try-merge c771610
    (DbConnector) $ git merge try-merge
    Auto-merging src/main.c
    CONFLICT (content): Merge conflict in src/main.c
    Recorded preimage for 'src/main.c'
    Automatic merge failed; fix conflicts and then commit the result.
    我们在这儿得到了一个真正的合并冲突，所以如果想要解决并提交它，那么只需简单地通过结果来更新主项目。
    
    $ vim src/main.c (1)
    $ git add src/main.c
    $ git commit -am 'merged our changes'
    Recorded resolution for 'src/main.c'.
    [master 9fd905e] merged our changes
    
    $ cd .. (2)
    $ git diff (3)
    diff --cc DbConnector
    index eb41d76,c771610..0000000
    --- a/DbConnector
    +++ b/DbConnector
    @@@ -1,1 -1,1 +1,1 @@@
    - Subproject commit eb41d764bccf88be77aced643c13a7fa86714135
     -Subproject commit c77161012afbbe1f58b5053316ead08f4b7e6d1d
    ++Subproject commit 9fd905e5d7f45a0d4cbc43d1ee550f16a30e825a
    $ git add DbConnector (4)
    
    $ git commit -m "Merge Tom's Changes" (5)
    [master 10d2c60] Merge Tom's Changes

1.  首先解决冲突
2.  然后返回到主项目目录中
3.  再次检查 SHA-1 值
4.  解决冲突的子模块记录
5.  提交我们的合并

这可能会让你有点儿困惑，但它确实不难

有趣的是，Git 还能处理另一种情况  
如果子模块目录中存在着这样一个合并提交，它的历史中包含了的两边的提交  
那么 Git 会建议你将它作为一个可行的解决方案  
它看到有人在子模块项目的某一点上合并了包含这两次提交的分支，所以你可能想要那个

这就是为什么前面的错误信息是 “`merge following commits not found`”，因为它不能这样做  
它让人困惑是因为谁能想到它会尝试这样做？

如果它找到了一个可以接受的合并提交，你会看到类似下面的信息：

$ git merge origin/master
    warning: Failed to merge submodule DbConnector (not fast-forward)
    Found a possible merge resolution for the submodule:
     9fd905e5d7f45a0d4cbc43d1ee550f16a30e825a: > merged our changes
    If this is correct simply add it to the index for example
    by using:
    
      git update-index --cacheinfo 160000 9fd905e5d7f45a0d4cbc43d1ee550f16a30e825a "DbConnector"
    
    which will accept this suggestion.
    Auto-merging DbConnector
    CONFLICT (submodule): Merge conflict in DbConnector
    Automatic merge failed; fix conflicts and then commit the result.

Git 建议的命令是更新索引，就像你运行了 `git add` 那样，这样会清除冲突然后提交  
不过你可能不应该这样做  
你可以轻松地进入子模块目录，查看差异是什么，快进到这次提交，恰当地测试，然后提交它

$ cd DbConnector/
    $ git merge 9fd905e
    Updating eb41d76..9fd905e
    Fast-forward
    
    $ cd ..
    $ git add DbConnector
    $ git commit -am 'Fast forwarded to a common submodule child'

这些命令完成了同一件事  
但是通过这种方式你至少可以验证工作是否有效  
以及当你在完成时可以确保子模块目录中有你的代码

--------------------

# 8. 子模的块技巧 #

可以做几件事情来让用子模块工作轻松一点儿

--------------------

## 8.1. 子模块遍历 ##

有一个 foreach 子模块命令，它能在每一个子模块中运行任意命令  
如果项目中包含了大量子模块，这会非常有用

例如，假设想要开始开发一项新功能或者修复一些错误，并且需要在几个子模块内工作  
我们可以轻松地保存所有子模块的工作进度

$ git submodule foreach 'git stash'
    Entering 'CryptoLibrary'
    No local changes to save
    Entering 'DbConnector'
    Saved working directory and index state WIP on stable: 82d2ad3 Merge from origin/stable
    HEAD is now at 82d2ad3 Merge from origin/stable

然后我们可以创建一个新分支，并将所有子模块都切换过去

$ git submodule foreach 'git checkout -b featureA'
    Entering 'CryptoLibrary'
    Switched to a new branch 'featureA'
    Entering 'DbConnector'
    Switched to a new branch 'featureA'

应该明白，能够生成一个主项目与所有子项目的改动的统一差异是非常有用的

$ git diff; git submodule foreach 'git diff'
    Submodule DbConnector contains modified content
    diff --git a/src/main.c b/src/main.c
    index 210f1ae..1f0acdc 100644
    --- a/src/main.c
    +++ b/src/main.c
    @@ -245,6 +245,8 @@ static int handle_alias(int *argcp, const char ***argv)
    
          commit_pager_choice();
    
    +     url = url_decode(url_orig);
    +
          /* build alias_argv */
          alias_argv = xmalloc(sizeof(*alias_argv) * (argc + 1));
          alias_argv[0] = alias_string + 1;
    Entering 'DbConnector'
    diff --git a/src/db.c b/src/db.c
    index 1aaefb6..5297645 100644
    --- a/src/db.c
    +++ b/src/db.c
    @@ -93,6 +93,11 @@ char *url_decode_mem(const char *url, int len)
            return url_decode_internal(&url, len, NULL, &out, 0);
     }
    
    +char *url_decode(const char *url)
    +{ 
    +       return url_decode_mem(url, strlen(url));
    +}
    +
     char *url_decode_parameter_name(const char **query)
     { 
            struct strbuf out = STRBUF_INIT;

在这里，我们看到子模块中定义了一个函数并在主项目中调用了它  
这明显是个简化了的例子，但是希望它能让你明白这种方法的用处

--------------------

## 8.2. 有用的别名 ##

可能想为其中一些命令设置别名  
因为它们可能会非常长而你又不能设置选项作为它们的默认选项  
我们在 Git 别名 介绍了设置 Git 别名  
但是如果你计划在 Git 中大量使用子模块的话，这里有一些例子

$ git config alias.sdiff '!'"git diff && git submodule foreach 'git diff'"
    $ git config alias.spush 'push --recurse-submodules=on-demand'
    $ git config alias.supdate 'submodule update --remote --merge'

这样当你想要更新子模块时可以简单地运行 `git supdate`，或 `git spush` 检查子模块依赖后推送

--------------------

# 9. 子模块的问题 #

然而使用子模块还是有一些小问题

--------------------

## 9.1. 切换分支 ##

例如，使用 Git 2.13 以前的版本时，在有子模块的项目中切换分支可能会造成麻烦  
如果你创建一个新分支，在其中添加一个子模块，之后切换到没有该子模块的分支上时  
仍然会有一个还未跟踪的子模块目录

$ git --version
    git version 2.12.2
    
    $ git checkout -b add-crypto
    Switched to a new branch 'add-crypto'
    
    $ git submodule add https://github.com/chaconinc/CryptoLibrary
    Cloning into 'CryptoLibrary'...
    ...
    
    $ git commit -am 'adding crypto library'
    [add-crypto 4445836] adding crypto library
     2 files changed, 4 insertions(+)
     create mode 160000 CryptoLibrary
    
    $ git checkout master
    warning: unable to rmdir CryptoLibrary: Directory not empty
    Switched to branch 'master'
    Your branch is up-to-date with 'origin/master'.
    
    $ git status
    On branch master
    Your branch is up-to-date with 'origin/master'.
    
    Untracked files:
      (use "git add <file>..." to include in what will be committed)
    
    	CryptoLibrary/
    
    nothing added to commit but untracked files present (use "git add" to track)

移除那个目录并不困难，但是有一个目录在那儿会让人有一点困惑  
如果你移除它然后切换回有那个子模块的分支  
需要运行 `submodule update --init` 来重新建立和填充

$ git clean -fdx
    Removing CryptoLibrary/
    
    $ git checkout add-crypto
    Switched to branch 'add-crypto'
    
    $ ls CryptoLibrary/
    
    $ git submodule update --init
    Submodule path 'CryptoLibrary': checked out 'b8dda6aa182ea4464f3f3264b11e0268545172af'
    
    $ ls CryptoLibrary/
    Makefile	includes	scripts		src

再说一遍，这真的不难，只是会让人有点儿困惑

新版的 Git（>= 2.13）通过为 `git checkout` 命令添加 `--recurse-submodules` 选项简化了所有这些步骤  
它能为了我们要切换到的分支让子模块处于的正确状态

$ git --version
    git version 2.13.3
    
    $ git checkout -b add-crypto
    Switched to a new branch 'add-crypto'
    
    $ git submodule add https://github.com/chaconinc/CryptoLibrary
    Cloning into 'CryptoLibrary'...
    ...
    
    $ git commit -am 'adding crypto library'
    [add-crypto 4445836] adding crypto library
     2 files changed, 4 insertions(+)
     create mode 160000 CryptoLibrary
    
    $ git checkout --recurse-submodules master
    Switched to branch 'master'
    Your branch is up-to-date with 'origin/master'.
    
    $ git status
    On branch master
    Your branch is up-to-date with 'origin/master'.
    
    nothing to commit, working tree clean

当你在父级项目的几个分支上工作时  
对 `git checkout` 使用 `--recurse-submodules` 选项也很有用  
它能让你的子模块处于不同的提交上

确实，如果你在记录了子模块的不同提交的分支上切换  
那么在执行 `git status` 后子模块会显示为“已修改”并指出“新的提交”  
这是因为子模块的状态默认不会在切换分支时保留

这点非常让人困惑，因此当你的项目中拥有子模块时  
可以总是使用 `git checkout --recurse-submodules`

> 对于没有 --recurse-submodules 选项的旧版 Git，在检出之后可使用 **git submodule update --init --recursive** 来让子模块处于正确的状态

幸运的是，可以通过 `git config submodule.recurse true` 设置 `submodule.recurse` 选项  
告诉 Git（>=2.14）总是使用 `--recurse-submodules`

如上所述  
这也会让 Git 为每个拥有 `--recurse-submodules` 选项的命令（除了 `git clone`） 总是递归地在子模块中执行

--------------------

## 9.2. 从子目录切换到子模块 ##

另一个主要的告诫是许多人遇到了将子目录转换为子模块的问题  
如果你在项目中已经跟踪了一些文件，然后想要将它们移动到一个子模块中，那么请务必小心  
假设项目内有一些文件在子目录中，你想要将其转换为一个子模块  
如果删除子目录然后运行 `submodule add`，Git 会朝你大喊：

$ rm -Rf CryptoLibrary/
    $ git submodule add https://github.com/chaconinc/CryptoLibrary
    'CryptoLibrary' already exists in the index

你=必须要先取消暂存 CryptoLibrary 目录  
然后才可以添加子模块：

$ git rm -r CryptoLibrary
    $ git submodule add https://github.com/chaconinc/CryptoLibrary
    Cloning into 'CryptoLibrary'...
    remote: Counting objects: 11, done.
    remote: Compressing objects: 100% (10/10), done.
    remote: Total 11 (delta 0), reused 11 (delta 0)
    Unpacking objects: 100% (11/11), done.
    Checking connectivity... done.

现在假设你在一个分支下做了这样的工作  
如果尝试切换回的分支中那些文件还在子目录而非子模块中时，会得到这个错误：

$ git checkout master
    error: The following untracked working tree files would be overwritten by checkout:
      CryptoLibrary/Makefile
      CryptoLibrary/includes/crypto.h
      ...
    Please move or remove them before you can switch branches.
    Aborting

可以通过 `checkout -f` 来强制切换  
但是要小心，如果其中还有未保存的修改，这个命令会把它们覆盖掉

$ git checkout -f master
    warning: unable to rmdir CryptoLibrary: Directory not empty
    Switched to branch 'master'

当切换回来之后，因为某些原因你得到了一个空的 CryptoLibrary 目录，并且 `git submodule update` 也无法修复它  
需要进入到子模块目录中运行 `git checkout .` 来找回所有的文件  
也可以通过 `submodule foreach` 脚本来为多个子模块运行它

要特别注意的是，近来子模块会将它们的所有 Git 数据保存在顶级项目的 `.git` 目录中  
所以不像旧版本的 Git，摧毁一个子模块目录并不会丢失任何提交或分支

拥有了这些工具，使用子模块会成为可以在几个相关但却分离的项目上同时开发的相当简单有效的方法

--------------------

参考： [git][]  
以上内容，均根据git官网介绍删减、添加和修改组成

--------------------