一、核心概念#

• Submodule 不是代码副本，而是一个 commit 指针（gitlink）
• 主仓库只记录：

  1
  ruoyi-ui -> 某一个 commit SHA
  

• 两个仓库 完全独立：commit / push / tag 都互不影响

二、如何判断是否存在子仓库#

1
ls .gitmodules
2
git submodule status
3
git ls-tree HEAD

出现 160000 commit xxxx ruoyi-ui 即表示 submodule。

三、Clone 正确方式#

1
git clone --recurse-submodules [email protected]:xxx/rentsys.git

1
git clone [email protected]:xxx/rentsys.git
2
cd rentsys
3
git submodule update --init --recursive

1
git checkout v0.0.3
2
git submodule update --init --recursive

四、日常开发 & 提交流程（最重要）#

1
cd ruoyi-ui
2
git checkout main
3
git pull
4
git add .
5
git commit -m "feat: ui change"
6
git push

1
cd ..
2
git add -A
3
git commit -m "feat: backend update + bump ruoyi-ui"
4
git push

五、为什么总是看到 ruoyi-ui (new commits)#

含义：子仓库前进了，但主仓库还没记录新指针。

解决：

1
git add ruoyi-ui
2
git commit -m "chore: bump ruoyi-ui"
3
git push

六、git add —all / git push 会发生什么？#

• ❌ 不会提交子仓库代码
• ✅ 只记录子仓库 commit 指针
• ❌ 不会自动 push 子仓库

⚠️ 子仓库未 push 就提交主仓库会导致灾难性不同步。

七、Tag 与 Submodule 的关系#

1
git tag -a v0.0.3 -m "release"
2
git push origin v0.0.3

1
# 子仓库
2
cd ruoyi-ui
3
git tag -a v0.0.3 -m "ui release"
4
git push origin v0.0.3
5

6
# 主仓库
7
cd ..
8
git tag -a v0.0.3 -m "full release"
9
git push origin v0.0.3

八、Pull 如何处理子仓库#

1
git pull
2
git submodule update --init --recursive

1
git pull
2
git submodule update --remote --merge
3
git add ruoyi-ui
4
git commit -m "chore: bump ruoyi-ui"
5
git push

九、Detached HEAD 处理#

发生场景：checkout tag / submodule 默认状态。

正确做法：

1
git checkout main
2
git cherry-pick <commit>
3
git push

十、工程级心法总结#

1️⃣ 子仓库代码只在子仓库提交
2️⃣ 主仓库只记录子仓库指针
3️⃣ 子仓库先 push，主仓库再 push
4️⃣ tag 不跨仓库，必须分别打
5️⃣ 切 tag / commit 后必须 update submodule

十一、推荐脚本（可扩展）#

• push_all.sh：一键 push UI + 主仓库
• pull_all.sh：pull + submodule update
• release.sh：双仓库打 tag + 校验

📌 本文档适用于长期维护的工程级 Git Submodule 项目。