184 lines
3.9 KiB
Markdown
184 lines
3.9 KiB
Markdown
|
||
---
|
||
|
||
# 🧩 Git Submodule 使用说明（父子仓库）
|
||
|
||
---
|
||
|
||
## ✅ 一、什么是子模块（Submodule）？
|
||
|
||
> 子模块允许你在一个 Git 仓库中嵌套另一个 Git 仓库作为子目录。适用于代码复用、模块化开发。
|
||
|
||
典型例子：
|
||
|
||
* 主仓库：`EdgeXAgent`
|
||
* 子仓库：`device-ble-go`（作为模块引入）
|
||
|
||
---
|
||
|
||
## ✅ 二、添加子模块
|
||
|
||
```bash
|
||
git submodule add <子仓库地址> <目标路径>
|
||
```
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
git submodule add git@github.com:yourname/device-ble-go.git res/device-ble-go
|
||
```
|
||
|
||
这会做两件事：
|
||
|
||
1. 在项目目录中添加子仓库代码到 `res/device-ble-go`
|
||
2. 创建 `.gitmodules` 文件，记录子模块信息
|
||
|
||
提交：
|
||
|
||
```bash
|
||
git add .gitmodules res/device-ble-go
|
||
git commit -m "Add device-ble-go as submodule"
|
||
git push
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 三、克隆带子模块的父仓库
|
||
|
||
### 方法一（推荐）：
|
||
|
||
```bash
|
||
git clone --recurse-submodules <父仓库地址>
|
||
```
|
||
|
||
### 方法二（先 clone，再初始化）：
|
||
|
||
```bash
|
||
git clone <父仓库地址>
|
||
cd 项目目录
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 四、更新子模块代码（获取最新提交）
|
||
|
||
进入子模块目录：
|
||
|
||
```bash
|
||
cd res/device-ble-go
|
||
git pull origin main # 拉取最新代码
|
||
```
|
||
|
||
回到主项目目录，更新引用：
|
||
|
||
```bash
|
||
cd ../..
|
||
git add res/device-ble-go
|
||
git commit -m "Update submodule device-ble-go to latest"
|
||
git push
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 五、一键更新所有子模块
|
||
|
||
```bash
|
||
git submodule update --remote --merge
|
||
```
|
||
|
||
或：
|
||
|
||
```bash
|
||
git submodule foreach git pull origin main
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 六、查看子模块状态
|
||
|
||
```bash
|
||
git submodule status
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 七、删除子模块
|
||
|
||
⚠️ 删除子模块不止 `rm`，需要多个步骤：
|
||
|
||
```bash
|
||
# 1. 删除子模块的 tracked 信息
|
||
git rm --cached res/device-ble-go
|
||
|
||
# 2. 删除子模块目录
|
||
rm -rf res/device-ble-go
|
||
|
||
# 3. 编辑 .gitmodules 文件，手动删掉对应的条目
|
||
|
||
# 4. 如果有 .git/config 里也记录了子模块，清除：
|
||
git config -f .git/config --remove-section submodule.res/device-ble-go
|
||
|
||
# 5. 提交更改
|
||
git commit -m "Remove submodule device-ble-go"
|
||
git push
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 八、配置 .gitmodules（自动跟踪分支）
|
||
|
||
默认子模块是绑定某个 commit，可以改成绑定分支：
|
||
|
||
编辑 `.gitmodules` 文件：
|
||
|
||
```ini
|
||
[submodule "res/device-ble-go"]
|
||
path = res/device-ble-go
|
||
url = git@github.com:yourname/device-ble-go.git
|
||
branch = main
|
||
```
|
||
|
||
之后用这个命令自动拉子模块的指定分支：
|
||
|
||
```bash
|
||
git submodule update --remote --merge
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 九、常见问题与解答
|
||
|
||
| 问题 | 解决方法 |
|
||
| ----------------------- | ----------------------------------------------- |
|
||
| 子模块目录是空的 | 没有初始化：`git submodule update --init --recursive` |
|
||
| 修改了子模块内容但父仓库没变 | 需要在父仓库中 `git add <子模块>` 并提交更新引用 |
|
||
| 克隆下来没有子模块内容 | 用 `--recurse-submodules` 或手动 `submodule update` |
|
||
| 子模块 push 后，别人 pull 没有更新 | 子模块更新后，要在父仓库提交“引用变化” |
|
||
|
||
---
|
||
|
||
## ✅ 十、推荐项目结构
|
||
|
||
```
|
||
EdgeXAgent/
|
||
├── .gitmodules
|
||
├── main.go
|
||
└── res/
|
||
└── device-ble-go/ <-- 子模块（独立 Git 仓库）
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 总结常用命令表
|
||
|
||
| 操作 | 命令 |
|
||
| ------- | ----------------------------------------- |
|
||
| 添加子模块 | `git submodule add URL path` |
|
||
| 初始化子模块 | `git submodule update --init --recursive` |
|
||
| 克隆并带子模块 | `git clone --recurse-submodules` |
|
||
| 更新所有子模块 | `git submodule update --remote --merge` |
|
||
| 删除子模块 | 多步骤，见上 |
|
||
| 查看状态 | `git submodule status` |
|
||
|
||
--- |