Git submodule 子模块的管理和使用

1. 使用前提

• 经常碰到这种情况，当你在一个 Git 项目上工作时，你需要在其中使用另一个 Git 项目，也许它是一个第三方开发的 Git 库或者是你独立开发和并在多个父项目中使用的。
• 这个情况下一个常见的问题产生了：你想将两个项目单独处理但是又需要在其中一个中使用另外一个。
• 在 Git 中你可以使用子模块 submodule 来管理这些项目，submodule 允许你将一个 Git 仓库当作另外一个 Git 仓库的子目录。这允许你克隆另外一个仓库到你的项目中并且保持你的提交相对独立。

备注：如果远程项目已关联 sumodule，客户端 clone 父项目与子模块，直接跳到第 5 步操作。

2. 添加子模块

$ git submodule add git@xxx:xxx/xxx.git xxx

• 添加子模块后运行 git status，可以看到目录增加一个文件 .gitmodules，这个文件用来保存
  子模块信息。

$ git status

On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

	new file:   .gitmodules
	new file:   backstage

3. 查看子模块

$ git submodule

be87a041e0d4c2547d9516b4b270c153469710c2 backstage (heads/master)

4. 更新子模块

- 更新项目内子模块到最新版本：
$ git submodule update

- 更新子模块为远程项目的最新版本：
$ git submodule update --remote

5. 克隆包含子模块的项目

• 克隆包含子模块的项目有二种方法：一种是先克隆父项目，再更新子模块；另一钟
  是直接递归克隆整个项目。
• （1）克隆父项目，再更新子模块

(1) 克隆父项目
$ git clone git@xxx:xxx/xxx.git --branch=xxx

(2) 查看子模块
$ git submodule
$ -be87a041e0d4c2547d9516b4b270c153469710c2 lib/backstage
- 子模块前面有一个-，说明子模块文件还未检入（空文件夹）

(3) 初始化子模块
$ git submodule init 
& Submodule 'xxx' (git@xxx:xxx/xxx/xxx.git) registered for path 'xxx/xxx'
- 初始化模块只需在克隆父项目后运行一次

(4) 更新子模块
$ git submodule update
$ Cloning into 'xxx/xxx/xxx'
$ ...
$ Submodule path 'xxx/xxx': checked out 'be87a041e0d4c2547d9516b4b270c153469710c2'

• （2）递归克隆整个项目

 $ git clone git@xxx:xxx/xxx.git --branch=xxx --recursive

• 递归克隆整个项目，子模块已经同时更新了，一步到位

6. 修改子模块

• 在子模块中修改文件后，直接提交到远程项目分支

$ git add .
$ git ci -m "commit"
$ git push origin HEAD:master

7. 删除子模块

• 删除子模块比较麻烦，需要手动删除相关的文件，否则在添加子模块时有可能出现错误。
• 以删除 backstage 文件夹为例：

(1) 删除子模块文件夹
$ git rm --cached backstage
$ rm -fr backstage

(2) 删除 .gitmodules 文件中相关子模块信息
[submodule "backstage"]
	path = xxx/backstage
	url = git@xxx:xxx/xxx/backstage.git
	ignore = all

(3) 删除 .git/config 中的相关子模块信息
[submodule "backstage"]
	url = git@xxx:xxxx/xxx/backstage.git

(4) 删除 .git 文件夹中的相关子模块文件
$ rm -fr .git/modules/backstage

8. 忽略 submodule 中的修改或新增文件

• 我们引用第三方的 project，大多数情况都是想以“只读”的方式引用，不关心第三方 project 抓取下来之后是不是被修改，或者是在其目录添加了 untracked 的 file，因为我们只是拉取第三方的 project，而不会（往往是不能或不允许）对第三方 project 进行提交。
• 在添加 submodule 之后，project 目录下会生成一个 .gitmodules 文件，这个文件记录了子模块的路径和仓库地址等信息，如下所示：

$ cat .gitmodules
[submodule "backstage"]
	path = lib/backstage
	url = git@xxx:xxx/component/backstage.git

• 我们要做的就是在 [submodule "project"] 中添加一个 ignore 子项，这个 ignore 子项可以有三个可选值 untracked、dirty 和 all，它们的意思分别是：
• untracked：忽略在子模块新添加的，未受版本控制的内容；
• dirty：忽略对子模块目录下受版本控制的内容进行的修改；
• all：同时忽略 untracked 和 dirty。
• 在添加 ignore 子项之后的 .gitmodules 文件的内容如下所示：

[submodule "backstage"]
	path = lib/backstage
	url = git@xxx:xxx/component/backstage.git
	ignore = all

9. 将已有工程子目录子模块化

如何把 Git 仓库的子目录独立为子模块

• （1）clone 一个新的待处理的仓库；
• （2）选择要保存的分支，如果我们希望在马上要做的子模块中保存其他的分支，那就首先把它们创建出来；
• （3）移除 origin 的 remote 信息 git remote rm origin
• （4）转化成子模块
• 例如子模块为 startup

$ git filter-branch --tag-name-filter cat --prune-empty --subdirectory-filter startup -- --all

• 该命令过滤所有历史提交，保留对 startup 子目录有影响的提交，并且把子目录设为该仓库的根目录
• （5）清理，减小仓库体积

$ git reset --hard
$ git for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d
$ git reflog expire --expire=now --all
$ git gc --aggressive --prune=now

• （6）删除无用的原工程上述命令未清理掉的目录

$ rm -fr app/
$ rm -fr .idea/
$ rm -fr .gradle/
$ rm -fr build/
$ rm -fr startup/
$ rm -fr local.properties
...

• （7）在远端创建对应的子模块仓库，推送代码到新的仓库

- 添加新的远程仓库
$ git remote add origin git@xxx:androidclient/modules/business/startup.git
- 推送所有分支到远端
$ git push -u origin --all
- 推送所有标签
$ git push origin --tags