GateWay/.qwen/skills/auto-skill-submodule-commit-push/SKILL.md

name, description, source, extracted_at

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

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

适用场景

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

核心原则

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

操作流程

1. 检查整体状态

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

2. 逐个检查子模块

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

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. 提交并推送每个子模块

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

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

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

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

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

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

6. 验证

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 分支