UGit 多仓库分支管理说明

1. 当前项目情况

TMR 项目由多个相互独立的 Git 子仓库组成。
各仓库的主开发分支均为 develop。
首充功能相关修改保存在 first_charge 分支中。
first_charge 已发布并推送到远端，主要用于导师查看。
首充内容原则上不合并回 develop。
日常开发继续使用 develop，需要查看或修改首充时再切换到 first_charge。

注意：准确的分支名是 first_charge。firstcharge、first_chagre 等拼写会被 Git 视为其他分支。

2. 分支之间的关系

develop 和 first_charge 是两套不同的代码快照。

在 develop 中，看不到只提交在 first_charge 中的首充内容。
切回 develop 不会删除或丢失首充代码。
首充代码仍保存在：
- 本地 first_charge 分支；
- 远端 origin/first_charge 分支。
切换回 first_charge 后，就可以重新看到首充内容。
develop 后续新增的代码不会自动进入 first_charge。

3. 日常推荐工作方式

3.1 平时开发

平时保持在 develop 分支，并同步远端最新代码：

1 2	git switch develop git pull --ff-only origin develop

使用 UGit 时，应先确认当前仓库位于 develop，然后执行更新。

3.2 查看首充内容

需要查看首充时：

1 2	git switch first_charge git pull origin first_charge

查看完成后切回：

1 2	git switch develop git pull --ff-only origin develop

3.3 修改并提交首充内容

推荐直接在 first_charge 上修改，不要在 develop 上恢复首充代码后绕行提交。

完整流程如下：

# 确保当前未提交的修改已处理完毕
git status

# 切换到首充分支
git switch first_charge

# 获取首充分支的远端最新版本
git pull origin first_charge

# 修改完成后暂存、提交并推送
git add <修改的文件>
git commit -m "调整首充内容"
git push origin first_charge

# 完成后切回主开发分支
git switch develop
git pull --ff-only origin develop

使用 UGit 时，对应操作顺序为：

确认当前工作区没有未处理的修改。
切换到 first_charge。
更新 first_charge。
修改首充内容。
暂存修改。
提交到本地 first_charge。
推送到远端 origin/first_charge。
切换回 develop。
更新 develop。

4. 如何减少频繁切换分支

如果只是偶尔修改首充，最简单、安全的方式是：

平时一直使用 develop。
确定需要修改首充时，一次性切换到 first_charge。
集中完成所有首充修改、测试、提交和推送。
全部完成后再切回 develop。

这样一次首充修改通常只需要切换两次，不建议通过反复储藏和恢复首充代码来避免切换。

如果以后需要长期同时维护两个分支，可以考虑：

为 develop 和 first_charge 分别准备独立工作目录；
使用 Git Worktree。

但 TMR 包含多个独立仓库，Worktree 配置和维护会更加复杂，只有在确实需要长期并行开发时再使用。

5. Stash（储藏）的正确理解

Stash 只用于保存当前工作区中尚未提交的本地修改。

它不是：

远端分支的最新版本；
一个正式提交；
一个可以替代分支的长期存储位置；
自动同步到云端的备份。

因此，不建议采用以下流程：

在 develop 恢复首充储藏；
修改首充；
再次储藏；
切换到 first_charge；
恢复并提交。

这种操作虽然在部分情况下可行，但容易出现：

首充修改意外混入 develop；
同一补丁被重复恢复；
恢复时产生冲突；
储藏内容与当前分支版本不匹配；
忘记删除或误删储藏。

正确做法仍然是直接切换到 first_charge 后修改。

如果确实需要使用储藏，优先使用 Apply 恢复，确认代码正确后再手动删除对应储藏，避免直接 Pop 后因冲突导致处理困难。

6. 蓝色圆点和“更新”操作

UGit 中的蓝色圆点通常表示对应仓库或分支存在待同步状态，例如远端有新的提交需要拉取。

由于不同 UGit 版本的界面含义可能略有差异，操作前应查看更新详情，确认：

蓝点对应的是哪个仓库；
当前选中的是哪个分支；
更新来自哪个远端分支；
是否存在本地未提交修改。

如果当前已经位于 first_charge，并且更新详情显示来源是 origin/first_charge，通常可以点击“更新”。这只会更新当前首充分支，不会把首充内容合并到 develop。

如果当前位于 develop，更新前应确认来源是 origin/develop。

更新前建议满足以下条件：

当前分支名称正确；
工作区干净，或者未提交修改已经提交/储藏；
更新详情中的远端分支与当前分支一致。

7. 防止 `first_charge` 长期不更新后无法运行

随着 develop 持续更新，两个分支之间的差异会越来越大。公共框架、Lua 接口、UI 资源或配置格式发生变化后，旧的 first_charge 可能无法正常启动或运行。

解决方法是按需把最新的 develop 单向合入 first_charge：

# 更新 develop
git switch develop
git pull --ff-only origin develop

# 更新 first_charge
git switch first_charge
git pull origin first_charge

# 将 develop 的新内容合入 first_charge
git merge develop

# 解决冲突并测试后，推送首充分支
git push origin first_charge

正确方向：

1	develop → first_charge

禁止反向操作：

1	first_charge → develop

否则可能把首充功能意外合入主开发分支。

建议同步时机

不需要每天同步，可以在以下情况执行：

准备给导师演示首充之前；
再次开始修改首充之前；
develop 出现较大的框架、UI、资源或配置调整之后；
first_charge 已经无法启动或出现明显兼容问题时。

合并冲突处理原则

发生冲突时，一般遵循：

公共框架和基础接口优先适配 develop 的新版本；
保留 first_charge 中首充业务本身的修改；
不要简单选择“全部保留某一侧”；
合并完成后必须完整测试首充流程。

8. 多仓库项目的特别注意事项

TMR 中每个子仓库都是独立 Git 仓库，因此分支操作需要分别执行。

例如，首充同时修改了 Lua、UI、资源和配置仓库，则这些仓库都应保持在相互兼容的分支和版本上。

切换或同步时应注意：

找出所有包含首充修改的子仓库。
在这些仓库中统一切换到 first_charge。
分别拉取各仓库的 origin/first_charge。
修改后分别提交并推送。
如果把 develop 合入 first_charge，相关仓库应协调同步。
完成后统一切回 develop。

如果部分仓库停留在 develop、部分仓库停留在旧的 first_charge，可能导致：

Lua 接口不匹配；
UI 或资源缺失；
配置字段结构不一致；
启动或运行时报错。

9. 最终推荐方案

日常状态

所有仓库保持在 develop。
正常拉取和开发最新主线内容。

需要查看或修改首充时

将所有相关仓库切换到 first_charge。
拉取远端首充分支。
集中完成修改、测试、提交和推送。

首充分支过旧时

先更新 develop。
再切换到 first_charge。
将 develop 单向合入 first_charge。
解决冲突并完整测试。
只推送 first_charge。

完成后

所有相关仓库统一切回 develop。
继续正常主线开发。

核心原则可以概括为：

平时使用 develop
需要首充时切换 first_charge
首充分支过旧时，将 develop 单向合入 first_charge
永远不要把 first_charge 合入 develop

本文从 LearnByCompany 原始文档自动同步。