---
name: submodule-commit-push
description: 提交并推送含子模块的 Git 仓库（先子模块后父仓库，处理 detached HEAD / 落后远程等常见问题）
source: auto-skill
extracted_at: '2026-06-22T03:44:15.544Z'
---

# 提交并推送所有仓库（含子模块）

## 适用场景
项目包含多个 Git 子模块，需要将所有变更（子模块内文件删除/修改 + 父仓库指针更新）一次性提交并推送到远端。

## 核心原则

**子模块必须先于父仓库提交并推送**，否则父仓库的指针会指向尚未推送到远端的提交，导致其他人拉取失败。

## 操作流程

### 1. 检查整体状态

```bash
cd <项目根目录>
git status                    # 查看父仓库变更
git submodule status          # 查看子模块状态（+ 表示新提交，- 表示未初始化）
```

### 2. 逐个检查子模块

对每个有变更的子模块，进入目录检查：

```bash
cd <子模块路径>
git status
git diff HEAD --stat
git branch -a                 # 检查是否在 detached HEAD
git log -n 1 --oneline        # 检查是否落后远端
```

### 3. 处理子模块常见问题

| 问题 | 表现 | 解决方案 |
|------|------|----------|
| **落后远端** | `Your branch is behind 'origin/xxx' by N commits` | 先 `git stash` → `git pull` → `git stash pop`，再提交 |
| **detached HEAD** | 子模块不在任何分支上 | `git checkout -b develop` 或 `git checkout develop` 切到分支再提交 |
| **仅 modified content** | 父仓库显示 `modified content` 但子模块 `git status` 干净 | 子模块只有未提交的本地修改，需在子模块内 add + commit |

### 4. 提交并推送每个子模块

```bash
cd <子模块路径>
git add -A
git commit -m "chore: 具体变更描述

- 文件1: 变更说明
- 文件2: 变更说明"
git push origin <分支名>       # 首次推送新分支用 git push -u origin <分支名>
```

> **提交消息格式**：按用户偏好，需列出每个文件的变更说明，而非笼统总结。

### 5. 在父仓库更新子模块指针

```bash
cd <项目根目录>
git add <子模块路径1> <子模块路径2> ...
git commit -m "chore: 更新子模块指针到最新提交

- 子模块1: 变更说明
- 子模块2: 变更说明"
git push origin <分支名>
```

### 6. 验证

```bash
cd <项目根目录>
git status                     # 应显示 nothing to commit, working tree clean
git submodule status           # 所有子模块无 + 或 - 前缀
```

## 本项目子模块清单

| 子模块 | 路径 | 默认分支 | 远端地址 |
|--------|------|----------|----------|
| FatFS | `Project/GateWay/source/Module/FatFS` | master | 192.168.2.47 |
| GateWay_Debug | `Project/GateWay/source/Module/GateWay_Debug` | develop | 192.168.2.47 |
| SDCard | `Project/GateWay/source/Module/SDCard` | master | 192.168.2.47 |
| sx127x | `Project/GateWay/source/Module/sx127x` | develop | 192.168.2.47 |

> 父仓库 GateWay 的远端在 8.137.104.4，子模块的远端在 192.168.2.47（内网），注意网络可达性。

## 注意事项

- 如果子模块只有指针变更（无文件级修改），说明子模块已有新提交但父仓库指针未更新，只需在父仓库 `git add <子模块路径>` 即可
- FatFS 子模块容易因为 documents/ 目录产生大量 untracked 文件冲突，`git stash` 时加 `--include-untracked`
- sx127x 经常处于 detached HEAD 状态，操作前务必先切到 develop 分支