Git Tools - Submodules
1. 应用场景
需求
当你在一个项目 project1 上工作时，你需要在其中使用另外一个项目 lib1 。也许它是一个第三方开发的库或者是你独立开发和并在多个父项目 (priject2，prject2 ... ...)中使用的。这个场景下一个常见的问题产生了：你想将两个项目 priject1、lib1 单独处理但是又需要在其中一个 project1 中使用另外一个 lib1。
解决方案
不使用 git submodules 的方法：包含库
- 包含库：把 lib1 代码包含到 project1 （project2 、project3 ... ...）项目中
- 问题 ： 定制和部署 project 更加困难了。
- 产生问题的原因 ：因为你必须确保每个客户都拥有 lib1 。并且当 lib1 被修改时(fix bug)，任何在 project1 （project2 、project3 ... ...） 中对 lib1 的修改都很难归并。
《Git权威指南》
项目的版本库在某些情况下需要引用其他版本库中的文件，
例如公司积累了一套常用的函数库，被多个项目调用，显然这个函数库的代码不能直接放到某个项目的代码中，而是要独立为一个代码库，那么其他项目要调用公共函数库该如何处理呢？
分别把公共函数库的文件拷贝到各自的项目中会造成冗余，丢弃了公共函数库的维护历史，这显然不是好的方法。
Git Submodules
Git 通过子模块处理这个问题。子模块允许你将一个 Git 仓库当作另外一个Git仓库的子目录。这允许你克隆另外一个仓库到你的项目中并且保持你的提交相对独立。学会 git submodule 可以使项目中再也不会出现大量
重复的资源文件、公共类库。更不会出现多个版本，甚至一个客户多个项目风格存在各种差异。
2. Learning Example
本例子采用两个项目以及两个公共类库学习对submodule的操作
2.1 创建 Git Submodule 测试项目
2.1.1 准备环境
- 当前目录
➜ ~ pwd
/Users/yjizhang
➜ ~ mkdir -p submd/repos
- 创建需要的本地仓库
➜ ~ cd ~/submd/repos
➜ repos git --git-dir=lib1.git init --bare
Initialized empty Git repository in /Users/yjizhang/submd/repos/lib1.git/
➜ repos git --git-dir=lib2.git init --bare
Initialized empty Git repository in /Users/yjizhang/submd/repos/lib2.git/
➜ repos git --git-dir=p1.git init --bare
Initialized empty Git repository in /Users/yjizhang/submd/repos/p1.git/
➜ repos git --git-dir=p2.git init --bare
Initialized empty Git repository in /Users/yjizhang/submd/repos/p2.git/
➜ repos ls
lib1.git lib2.git p1.git p2.git
- 初始化工作区
➜ ~ mkdir ~/submd/ws
➜ ~ cd submd/ws
2.1.2 初始化项目
- 初始化 p1 (project1)
➜ ~ cd ~/submd/ws
➜ ws git clone ../repos/p1.git
Cloning into 'p1'...
warning: You appear to have cloned an empty repository.
done.
➜ ws cd p1
➜ p1 git:(master) echo "p1" >> p1-infos.txt
➜ p1 git:(master) ✗ ls
p1-infos.txt
➜ p1 git:(master) ✗ gst
On branch master
Initial commit
Untracked files:
(use "git add <file>..." to include in what will be committed)
p1-infos.txt
nothing added to commit but untracked files present (use "git add" to track)
➜ p1 git:(master) ✗ git add p1-infos.txt
➜ p1 git:(master) ✗ gst
On branch master
Initial commit
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: p1-infos.txt
➜ p1 git:(master) ✗ gc -m "init p1"
[master (root-commit) 960cb75] init p1
1 file changed, 1 insertion(+)
create mode 100644 p1-infos.txt
➜ p1 git:(master) git push origin master
Counting objects: 3, done.
Writing objects: 100% (3/3), 217 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To /Users/yjizhang/submd/ws/../repos/p1.git
* [new branch] master -> master
➜ p1 git:(master)
- 初始化 p2
➜ ~ cd ~/submd/ws
➜ ws git clone ../repos/p2.git
Cloning into 'p2'...
warning: You appear to have cloned an empty repository.
done.
➜ ws cd p2
➜ p2 git:(master) gst
On branch master
Initial commit
nothing to commit (create/copy files and use "git add" to track)
➜ p2 git:(master) echo "p2" >> p2-infos.txt
➜ p2 git:(master) ✗ ls
p2-infos.txt
➜ p2 git:(master) ✗ gst
On branch master
Initial commit
Untracked files:
(use "git add <file>..." to include in what will be committed)
p2-infos.txt
nothing added to commit but untracked files present (use "git add" to track)
➜ p2 git:(master) ✗ git add p2-infos.txt
➜ p2 git:(master) ✗ gst
On branch master
Initial commit
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: p2-infos.txt
➜ p2 git:(master) ✗ gc -m "init p2"
[master (root-commit) 449e7ed] init p2
1 file changed, 1 insertion(+)
create mode 100644 p2-infos.txt
➜ p2 git:(master) gst
On branch master
Your branch is based on 'origin/master', but the upstream is gone.
(use "git branch --unset-upstream" to fixup)
nothing to commit, working tree clean
➜ p2 git:(master) git push origin master
Counting objects: 3, done.
Writing objects: 100% (3/3), 217 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To /Users/yjizhang/submd/ws/../repos/p2.git
* [new branch] master -> master
➜ p2 git:(master)
2.1.3 初始化公共类库
- 初始化公共类库 lib1
➜ ~ cd ~/submd/ws
➜ ws git clone ../repos/lib1.git
Cloning into 'lib1'...
warning: You appear to have cloned an empty repository.
done.
➜ ws cd lib1
➜ lib1 git:(master) echo "I'm lib1" > lib1-features
➜ lib1 git:(master) ✗ git add lib1-features
➜ lib1 git:(master) ✗ gc -m "init lib1"
[master (root-commit) 101b2e6] init lib1
1 file changed, 1 insertion(+)
create mode 100644 lib1-features
➜ lib1 git:(master) git push origin master
Counting objects: 3, done.
Writing objects: 100% (3/3), 224 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To /Users/yjizhang/submd/ws/../repos/lib1.git
* [new branch] master -> master
- 初始化公共类库 lib2
➜ lib1 git:(master) cd ~/submd/ws
➜ ws git clone ../repos/lib2.git
Cloning into 'lib2'...
warning: You appear to have cloned an empty repository.
done.
➜ ws cd lib2
➜ lib2 git:(master) echo "I'm lib2" >> lib2-features
➜ lib2 git:(master) ✗ git add lib2-features
➜ lib2 git:(master) ✗ gc -m "init lib2"
[master (root-commit) fa8fdee] init lib2
1 file changed, 1 insertion(+)
create mode 100644 lib2-features
➜ lib2 git:(master) git push origin master
Counting objects: 3, done.
Writing objects: 100% (3/3), 225 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To /Users/yjizhang/submd/ws/../repos/lib2.git
* [new branch] master -> master
2.2 为主项目添加 Submodules
2.2.1 为 p1 添加 lib1 和 lib2
-
命令 ：
git submodule add
➜ cd ~/submd/ws/p1
➜ p1 git:(master) ls
p1-infos.txt
➜ p1 git:(master) git submodule add ~/submd/repos/lib1.git libs/lib1
Cloning into '/Users/yjizhang/submd/ws/p1/libs/lib1'...
done.
➜ p1 git:(master) ✗ git submodule add ~/submd/repos/lib2.git libs/lib2
Cloning into '/Users/yjizhang/submd/ws/p1/libs/lib2'...
done.
➜ p1 git:(master) ✗ gst
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: libs/lib1
new file: libs/lib2
➜ p1 git:(master) ✗ tree
.
├── libs
│ ├── lib1
│ │ └── lib1-features
│ └── lib2
│ └── lib2-features
└── p1-infos.txt
3 directories, 3 files
➜ p1 git:(master) ✗ cat libs/lib1/lib1-features
I'm lib1
➜ p1 git:(master) ✗ cat libs/lib2/lib2-features
I'm lib2
此时我们已经成功使用 git submodule add 命令为 p1 添加了两个公共类库 lib1 lib2，那么我们怎样查看子模块是否已经添加成功了呢 ？
2.2.2 查看 .gitmodules 的内容
- .gitmodules : 该文件记录了每个 submodule 的引用信息以及其在当前项目的位置以及仓库所在地址
➜ p1 git:(master) ✗ cat .gitmodules
[submodule "libs/lib1"]
path = libs/lib1
url = /Users/yjizhang/submd/repos/lib1.git
[submodule "libs/lib2"]
path = libs/lib2
url = /Users/yjizhang/submd/repos/lib2.git
2.2.3 提交添加子模块的更改
➜ p1 git:(master) ✗ gst
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: libs/lib1
new file: libs/lib2
➜ p1 git:(master) ✗ git commit -a -m "add submodule [lib1、lib2] to p1"
[master 65a41b4] add submodule [lib1、lib2] to p1
3 files changed, 8 insertions(+)
create mode 100644 .gitmodules
create mode 160000 libs/lib1
create mode 160000 libs/lib2
➜ p1 git:(master) git push
Counting objects: 4, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 488 bytes | 0 bytes/s, done.
Total 4 (delta 0), reused 0 (delta 0)
To /Users/yjizhang/submd/ws/../repos/p1.git
960cb75..65a41b4 master -> master
假设你是第一次引入公共类库 lib1、lib2 到 p1 的开发人员，name项目组的其他人要怎么 Clone 带有 Submodules 的项目呢 ？
2.3 Clone 带有 Submodule 的仓库
模拟开发人员 B Clone 带有 Submodule 的项目 p1
2.3.1 Clone 带有 submodule 的库 p1
➜ ~ cd ~/submd/ws
➜ ws git clone ../repos/p1.git p1-b
Cloning into 'p1-b'...
done.
➜ ws ls
lib1 lib2 p1 p1-b p2
# clone 成功，查看 p1-b dir tree
➜ ws cd p1-b
➜ p1-b git:(master) tree
.
├── libs
│ ├── lib1
│ └── lib2
└── p1-infos.txt
# 对比 p1-b 和 p1 的 dir tree
➜ p1-b git:(master) cd ../p1
➜ p1 git:(master) tree
.
├── libs
│ ├── lib1
│ │ └── lib1-features
│ └── lib2
│ └── lib2-features
└── p1-infos.txt
3 directories, 3 files
发现 我们 clone 的 p1-b 中 submodule [lib1、lib2] 的内容并没有 clone 下来。我们可以查看一下子模块，那么怎么查看子模块状态呢 ？
2.3.2 查看子模块状态 git submodule
➜ p1-b git:(master) git submodule
-101b2e60e0f8c759d2f60c7fca12f3b1e474de21 libs/lib1
-fa8fdeed9d7c8938c0fe470766c568fb32b1ed14 libs/lib2
➜ p1-b git:(master) cd ../p1
➜ p1 git:(master) git submodule
101b2e60e0f8c759d2f60c7fca12f3b1e474de21 libs/lib1 (heads/master)
fa8fdeed9d7c8938c0fe470766c568fb32b1ed14 libs/lib2 (heads/master)
- 表示该子模块还没有检出，怎么检出子模块内容 ?
2.3.3 检出子模块内容 git submodule init & git submodule update
-
git submodule init初始化本地配置文件.git/config -
git submodule update从指定项目.git/config拉取所有数据并检出你上层项目里所列的合适的提交
➜ p1-b git:(master) git submodule
-101b2e60e0f8c759d2f60c7fca12f3b1e474de21 libs/lib1
-fa8fdeed9d7c8938c0fe470766c568fb32b1ed14 libs/lib2
➜ p1-b git:(master) cat .git/config
[core]
repositoryformatversion = 0
filemode = true
bare = false
logallrefupdates = true
ignorecase = true
precomposeunicode = true
[remote "origin"]
url = /Users/yjizhang/submd/ws/../repos/p1.git
fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
remote = origin
merge = refs/heads/master
➜ p1-b git:(master) git submodule init
Submodule 'libs/lib1' (/Users/yjizhang/submd/repos/lib1.git) registered for path 'libs/lib1'
Submodule 'libs/lib2' (/Users/yjizhang/submd/repos/lib2.git) registered for path 'libs/lib2'
➜ p1-b git:(master) cat .git/config
[core]
repositoryformatversion = 0
filemode = true
bare = false
logallrefupdates = true
ignorecase = true
precomposeunicode = true
[remote "origin"]
url = /Users/yjizhang/submd/ws/../repos/p1.git
fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
remote = origin
merge = refs/heads/master
[submodule "libs/lib1"]
url = /Users/yjizhang/submd/repos/lib1.git
[submodule "libs/lib2"]
url = /Users/yjizhang/submd/repos/lib2.git
➜ p1-b git:(master) git submodule update
Cloning into '/Users/yjizhang/submd/ws/p1-b/libs/lib1'...
done.
Cloning into '/Users/yjizhang/submd/ws/p1-b/libs/lib2'...
done.
Submodule path 'libs/lib1': checked out '101b2e60e0f8c759d2f60c7fca12f3b1e474de21'
Submodule path 'libs/lib2': checked out 'fa8fdeed9d7c8938c0fe470766c568fb32b1ed14'
➜ p1-b git:(master) git submodule
101b2e60e0f8c759d2f60c7fca12f3b1e474de21 libs/lib1 (heads/master)
fa8fdeed9d7c8938c0fe470766c568fb32b1ed14 libs/lib2 (heads/master)
➜ p1-b git:(master) tree
.
├── libs
│ ├── lib1
│ │ └── lib1-features
│ └── lib2
│ └── lib2-features
└── p1-infos.txt
3 directories, 3 files
➜ p1-b git:(master) cat libs/lib1/lib1-features libs/lib2/lib2-features
I'm lib1
I'm lib2
2.4 修改该有 Submodule 的库
模拟开发人员 B 修改子模块内容
2.4.1 查看子模块
➜ p1-b git:(master) cd libs/lib1
➜ lib1 git:(101b2e6) gst
HEAD detached at 101b2e6
nothing to commit, working tree clean
发现子模块 lib1 在一个匿名的分支上，为什么 ？
原因： Git 对于 Submodule 有特殊的处理方式。
-
一个主项目中引入 Submodule 其实 Git 做了三件事
- 记录引用的仓库 （子模块仓库描述）
- 记录主项目中 Submodule 的目录位置
- 记录引用 Submodule 的 commit id
说明：
在 p1 中 push 之后其实是在 p1 中记录了对 submodule 提交的引用 commit id
然后 p1-b 在 clone p1 的时候获取到了 p1 对 submodule 提交的引用 commit id
当 p1-b 中执行 git submodule update 的时候, git 根据 modules 获取到了 submodule 的 commit id , 然后获取 submodule 的文件。
所以 clone 之后子模块不在任何分支上，但是 master 分支和 commit id 和 HEAD 保持一致。
2.4.2 更新子模块
- 切换到 master 分支
- 更新子模块内容
- 提交子模块更新
- 提交主项目中子模块更新引用
# 切换到 master 分支
➜ p1-b git:(master) cd libs/lib1
➜ lib1 git:(101b2e6) gco master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.
# 更新子模块内容
➜ lib1 git:(master) echo "add by developer b" >> lib1-features
# 提交子模块更新
➜ lib1 git:(master) ✗ ga .
➜ lib1 git:(master) ✗ gc -m "update lib1-feature by dev b"
[master 241e03b] update lib1-feature by dev b
1 file changed, 1 insertion(+)
➜ lib1 git:(master) git push
Counting objects: 3, done.
Writing objects: 100% (3/3), 286 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To /Users/yjizhang/submd/repos/lib1.git
101b2e6..241e03b master -> master
# 提交主项目中子模块更新引用
➜ lib1 git:(master) cd ../../
➜ p1-b git:(master) ✗ git diff
diff --git a/libs/lib1 b/libs/lib1
index 101b2e6..241e03b 160000
--- a/libs/lib1
+++ b/libs/lib1
@@ -1 +1 @@
-Subproject commit 101b2e60e0f8c759d2f60c7fca12f3b1e474de21
+Subproject commit 241e03bf0bf574063417c05a1d558fa4a6006425
(END)
➜ p1-b git:(master) ✗ gst
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: libs/lib1 (new commits)
no changes added to commit (use "git add" and/or "git commit -a")
➜ p1-b git:(master) ✗ git add libs/lib1
➜ p1-b git:(master) ✗ gst
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
(use "git reset HEAD <file>..." to unstage)
modified: libs/lib1
➜ p1-b git:(master) ✗ gc -m "update libs/lib1 to lastest commit id"
[master ea785a2] update libs/lib1 to lastest commit id
1 file changed, 1 insertion(+), 1 deletion(-)
➜ p1-b git:(master) git push
Counting objects: 3, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 389 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To /Users/yjizhang/submd/ws/../repos/p1.git
65a41b4..ea785a2 master -> master
现在我们已经在 p1-b 中更新了子模块 lib1 的内容。那么我们怎样同步更新 p1 中 lib1 的内容呢 ？
2.5 更新主项目的 Submodule
- 拉取主项目最新更新
git pull或git pull -r (推荐.其会将本地提交放在远程提交的最后，减少冲突) - 拉取子模块更新的内容
git submodule update(注：在执行前明确保已经执行了git submodule init将子模块信息注册到.git/congfig中)
➜ p1-b git:(master) cd ../p1
➜ p1 git:(master) gst
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working tree clean
➜ p1 git:(master) git pull
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
From /Users/yjizhang/submd/ws/../repos/p1
65a41b4..ea785a2 master -> origin/master
Fetching submodule libs/lib1
From /Users/yjizhang/submd/repos/lib1
101b2e6..241e03b master -> origin/master
Updating 65a41b4..ea785a2
Fast-forward
libs/lib1 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
➜ p1 git:(master) ✗ gst
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: libs/lib1 (new commits)
no changes added to commit (use "git add" and/or "git commit -a")
➜ p1 git:(master) ✗ git submodule update
Submodule path 'libs/lib1': checked out '241e03bf0bf574063417c05a1d558fa4a6006425'
➜ p1 git:(master) cat libs/lib1/lib1-features
I'm lib1
add by developer b
