---

# 🧩 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`                    |

---