Git Submodule 命令

1. 添加子模块#

1
git submodule add <仓库URL> <本地路径>

执行后会生成 .gitmodules 文件，并记录子模块当前所在的 commit。

2. 克隆含有子模块的仓库#

• 一步到位克隆：

  1
  git clone --recurse-submodules <主仓库URL>

• 已克隆但子模块为空时，手动初始化并更新：

  1
  git submodule update --init --recursive

此处的--init​参数相当于先执行init​子命令后再执行update​子命令，git submodule init​会根据 .gitmodules​ 文件的信息，初始化本地 Git 配置（.git/config），

3. 更新子模块#

• 将子模块更新到远程仓库的最新提交：

  1
  git submodule update --remote

• 更新后，主仓库中记录的子模块指针会变化，需要手动提交：

  1
  git add <子模块路径>
  2
  git commit -m "更新子模块到最新版本"

4. 查看子模块状态#

1
git submodule status

输出中前缀含义：

• ​- 表示未初始化
• ​+ 表示当前检出的提交与主仓库记录的提交不一致

5. 删除子模块#

1
git submodule deinit <路径>
2
git rm <路径>
3
rm -rf .git/modules/<路径>

最后提交删除操作。

6. 同步子模块 URL#

​sync​子命令，它的作用是将.gitmodules​文件中定义的远程 URL 同步到本地 Git 配置（.git/config）中。

1
# 同步所有子模块
2
git submodule sync
3

4
# 同步指定子模块
5
git submodule sync <子模块路径>
6

7
# 递归同步（子模块嵌套时）
8
git submodule sync --recursive

1. .gitmodules —— 版本控制的配置文件#

位于主仓库根目录，采用 INI 格式，记录了子模块的逻辑路径和远程 URL。该文件随主仓库一起版本控制，他人克隆后可见。

1
[submodule "libs/mylib"]
2
    path = libs/mylib
3
    url = https://github.com/example/lib.git
4
[submodule "vendor/other"]
5
    path = vendor/other
6
    url = git@gitlab.com:team/other.git
7
    branch = develop

• ​path：子模块在主仓库中的相对路径。
• ​url：子模块的远程仓库地址。
• 可选字段如 branch​，指定 git submodule update --remote 时跟踪的分支（不写则默认跟踪主仓库记录的 commit）。

2. .git/config —— 本地仓库配置（不版本控制）#

执行 git submodule init​ 后，.gitmodules​ 中的配置会被复制到 .git/config 中，形成类似结构：

1
[submodule "libs/mylib"]
2
    url = https://github.com/example/lib.git
3
    active = true

• 后续 git submodule update​ 等命令实际读取的是此处的 url。
• 若 .gitmodules​ 中的 URL 变化，需手动执行 git submodule sync 来同步此处。
• 该文件仅在本地存在，不会被提交，每个人的副本独立。

3. 主仓库的树对象 —— 子模块指针的存储#

子模块本质上是一个类型为 commit 的 Git 对象，它在主仓库每一次提交的树对象中表现为一个特殊条目：

• 模式：160000​（普通文件是 100644​，目录是 040000）。
• 名称：子模块的目录名。
• 哈希：指向子模块仓库中某一个具体 commit 的 SHA-1 值。

用底层命令可查看到类似：

1
$ git ls-tree HEAD libs/mylib
2
160000 commit 1a2b3c4d...  libs/mylib

这个 commit SHA 决定了子模块检出到哪个版本。当你在主仓库中 git add libs/mylib 并提交时，实际上就是更新了这个哈希值。

4. .git/modules/<路径> —— 子模块实际的 Git 数据#

子模块本身的仓库（对象库、引用等）存储在主仓库的 .git/modules/<子模块路径>​ 目录下（旧版本 Git 直接存放在子模块目录内的 .git 文件中）。
这个目录对用户一般是透明的，但它是子模块能独立进行 Git 操作的基础。

将子文件夹独立为子模块#

假设原仓库结构：

1
my-project/
2
├── .git/
3
├── target-folder/       ← 想独立为子模块的文件夹
4
│   ├── a.txt
5
│   └── b.js
6
└── other-stuff/

最终：target-folder​ 变成一个独立的 Git 仓库，并在原仓库中作为子模块引用，且所有历史提交（仅针对 target-folder/ 的修改）都保留在新仓库里。