hyf/reademe/submodule/reademe.md

# HYF 项目

这是一个使用 Git Submodules 管理的 Maven 多模块项目。

## 项目结构

```
hyf/
├── pom.xml                           # 父项目 POM
├── thingsboard-client-demo/          # 子模块1（Git Submodule）
└── thingsboard-gateway-ws-demo/      # 子模块2（Git Submodule）
```

---

## 一、如何添加一个新的 Module

### 1.1 创建并初始化新模块的 Git 仓库

```bash
# 在本地创建新模块目录和代码
cd /Users/sunpeng/workspace/hyf
mkdir new-module
cd new-module

# 初始化 Git 仓库
git init
git add .
git commit -m "Initial commit: new module"

# 关联远程仓库并推送
git remote add origin <新模块的远程仓库URL>
git branch -M main
git push -u origin main
```

### 1.2 将新模块添加为 Submodule

```bash
# 回到根目录
cd /Users/sunpeng/workspace/hyf

# 删除本地的新模块目录
rm -rf new-module

# 添加为 Git Submodule
git submodule add <新模块的远程仓库URL> new-module

# 提交 submodule 配置
git add .
git commit -m "Add new-module as submodule"
git push
```

### 1.3 更新父项目 pom.xml

编辑根目录的 `pom.xml`，在 `<modules>` 标签中添加新模块：

```xml
<modules>
  <module>thingsboard-client-demo</module>
  <module>thingsboard-gateway-ws-demo</module>
  <module>new-module</module>
</modules>
```

提交修改：

```bash
git add pom.xml
git commit -m "Add new-module to parent pom"
git push
```

---

## 二、如何更新 Module（子模块）

### 2.1 修改子模块代码

```bash
# 进入子模块目录
cd thingsboard-client-demo

# 修改代码后提交
git add .
git commit -m "描述你的修改内容"
git push
```

### 2.2 在主仓库中更新子模块引用

**重要**：修改子模块后，主仓库需要更新对子模块 commit 的引用。

```bash
# 回到根目录
cd /Users/sunpeng/workspace/hyf

# 查看子模块状态（会显示子模块有新的 commit）
git status

# 提交子模块引用的更新
git add thingsboard-client-demo
git commit -m "Update thingsboard-client-demo submodule"
git push
```

### 2.3 同时修改多个子模块

```bash
# 1. 提交第一个子模块
cd thingsboard-client-demo
git add .
git commit -m "修改客户端代码"
git push

# 2. 提交第二个子模块
cd ../thingsboard-gateway-ws-demo
git add .
git commit -m "修改网关代码"
git push

# 3. 回到根目录，更新所有子模块引用
cd ..
git add .
git commit -m "Update submodules"
git push
```

---

## 三、如何拉代码并更新各个子模块

### 3.1 首次克隆项目（推荐方式）

```bash
# 一次性克隆主仓库和所有子模块
git clone --recursive <主仓库URL>
```

### 3.2 首次克隆项目（分步方式）

```bash
# 先克隆主仓库
git clone <主仓库URL>
cd hyf

# 初始化并拉取所有子模块
git submodule init
git submodule update
```

### 3.3 已有项目，拉取最新代码

```bash
cd /Users/sunpeng/workspace/hyf

# 拉取主仓库最新代码
git pull

# 更新所有子模块到主仓库记录的版本
git submodule update

# 或者：更新所有子模块到各自远程仓库的最新版本
git submodule update --remote
```

### 3.4 拉取特定子模块的最新代码

```bash
# 进入子模块目录
cd thingsboard-client-demo

# 拉取该子模块的最新代码
git pull origin main

# 回到根目录，提交子模块引用的更新
cd ..
git add thingsboard-client-demo
git commit -m "Update thingsboard-client-demo to latest"
git push
```

---

## 四、如何更新主模块和子模块

### 4.1 只修改了主模块（根目录文件）

```bash
cd /Users/sunpeng/workspace/hyf

# 修改了 pom.xml、.gitignore 等根目录文件
git add .
git commit -m "描述主模块的修改内容"
git push
```

### 4.2 同时修改了主模块和子模块

```bash
# 1. 先提交所有子模块的修改
cd thingsboard-client-demo
git add .
git commit -m "修改客户端代码"
git push

cd ../thingsboard-gateway-ws-demo
git add .
git commit -m "修改网关代码"
git push

# 2. 回到根目录，提交主模块和子模块引用的更新
cd ..
git add .
git commit -m "Update main module and submodules"
git push
```

### 4.3 团队协作：同步他人的修改

当其他人修改了主模块或子模块后，你需要同步：

```bash
cd /Users/sunpeng/workspace/hyf

# 拉取主仓库最新代码
git pull

# 更新所有子模块到主仓库记录的版本
git submodule update --init --recursive
```

**注意**：`--init` 参数会自动初始化新添加的子模块。

---

## 常用命令速查

### 查看状态

```bash
# 查看主仓库状态
git status

# 查看所有子模块状态
git submodule foreach git status

# 查看子模块的详细信息
git submodule status
```

### 批量操作子模块

```bash
# 在所有子模块中执行命令
git submodule foreach <command>

# 例如：在所有子模块中拉取最新代码
git submodule foreach git pull origin main

# 例如：在所有子模块中查看当前分支
git submodule foreach git branch
```

### 子模块更新

```bash
# 更新子模块到主仓库记录的版本
git submodule update

# 更新子模块到远程最新版本
git submodule update --remote

# 初始化并更新所有子模块（包括新添加的）
git submodule update --init --recursive
```

---

## Maven 构建

```bash
# 在根目录构建所有模块
mvn clean install

# 只构建特定模块
mvn clean install -pl thingsboard-client-demo

# 构建特定模块及其依赖
mvn clean install -pl thingsboard-client-demo -am
```

---

## 重要注意事项

1. **子模块修改流程**：先在子模块目录提交并推送，再回到主仓库更新子模块引用
2. **主仓库记录的是子模块的特定 commit**，不是分支名
3. **克隆项目时务必使用 `--recursive`**，或手动执行 `git submodule update --init`
4. **拉取代码后记得执行 `git submodule update`**，确保子模块版本正确
5. **团队协作时**，确保所有成员理解 submodule 的工作方式，避免子模块版本混乱

---

## 工作流程示例

### 日常开发流程

```bash
# 1. 早上开始工作，拉取最新代码
cd /Users/sunpeng/workspace/hyf
git pull
git submodule update --init --recursive

# 2. 修改子模块代码
cd thingsboard-client-demo
# ... 编写代码 ...
git add .
git commit -m "实现新功能"
git push

# 3. 更新主仓库的子模块引用
cd ..
git add thingsboard-client-demo
git commit -m "Update thingsboard-client-demo"
git push

# 4. 如果修改了主模块配置
git add pom.xml
git commit -m "更新依赖版本"
git push
```

### 添加新功能模块流程

```bash
# 1. 创建新模块仓库并推送
mkdir new-feature
cd new-feature
git init
# ... 创建代码 ...
git add .
git commit -m "Initial commit"
git remote add origin <新模块URL>
git push -u origin main

# 2. 添加为 submodule
cd /Users/sunpeng/workspace/hyf
rm -rf new-feature
git submodule add <新模块URL> new-feature

# 3. 更新 pom.xml
# 编辑 pom.xml，添加 <module>new-feature</module>
git add .
git commit -m "Add new-feature module"
git push
```