Git / UGit 多仓库分支管理通用说明

1. 适用场景

本文适用于以下常见情况：

  • 一个项目由一个或多个独立 Git 仓库组成；
  • 日常开发在主开发分支进行；
  • 某项功能、演示版本或实验性修改保存在独立分支；
  • 独立分支暂时不合并回主开发分支；
  • 偶尔需要查看、修改或维护该独立分支。

为便于说明，本文统一使用以下占位名称：

名称 含义 示例
<主开发分支> 日常开发使用的分支 develop、main
<功能分支> 保存特定功能或版本的分支 feature_xxx、demo_version
origin 默认远端仓库名称 origin

实际操作时，应将占位名称替换为项目中的真实分支名。

Git 会严格区分分支名称。拼写、下划线、连字符或大小写不一致，都可能指向不同分支或导致命令失败。

2. 分支之间的关系

Git 分支可以理解为不同的代码版本线或代码快照。

假设某项修改只提交在 <功能分支>：

  • 切换到 <主开发分支> 后，看不到该功能是正常现象；
  • 切换分支不会删除另一个分支中的代码；
  • 已提交并推送的代码通常同时保存在本地分支和远端分支中；
  • 重新切换到 <功能分支> 后，可以再次看到对应内容；
  • <主开发分支> 后续产生的新提交不会自动进入 <功能分支>；
  • 两个分支只有经过合并、变基或挑选提交等操作后，代码才会相互同步。

查看本地和远端分支：

1
2
3
git branch
git branch -r
git branch -a

查看当前分支及工作区状态：

1
git status

3. 日常推荐工作流程

3.1 在主开发分支进行日常开发

1
2
git switch <主开发分支>
git pull --ff-only origin <主开发分支>

推荐在开始工作前确认：

  1. 当前仓库是否正确；
  2. 当前分支是否为 <主开发分支>；
  3. 工作区是否存在未提交修改；
  4. 拉取的远端分支是否正确。

使用 UGit 等图形工具时，也应先确认仓库和当前分支，再执行“更新”或“拉取”。

3.2 查看功能分支

1
2
3
git status
git switch <功能分支>
git pull --ff-only origin <功能分支>

查看完成后切回主开发分支：

1
2
git switch <主开发分支>
git pull --ff-only origin <主开发分支>

如果本地尚未创建功能分支，但远端已经存在，可以执行：

1
2
git fetch origin
git switch --track origin/<功能分支>

3.3 修改并提交功能分支

推荐直接切换到目标功能分支后再修改，不要把功能代码临时恢复到其他分支中绕行提交。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 检查当前状态，先处理未提交修改
git status

# 切换并更新目标分支
git switch <功能分支>
git pull --ff-only origin <功能分支>

# 修改完成后检查差异
git status
git diff

# 暂存、提交并推送
git add <文件或目录>
git commit -m "描述本次修改"
git push origin <功能分支>

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

对应的 UGit 操作顺序通常为：

  1. 确认工作区没有未处理的修改；
  2. 切换到目标功能分支；
  3. 更新目标功能分支；
  4. 完成代码修改和测试；
  5. 暂存修改；
  6. 提交到本地功能分支；
  7. 推送到对应远端分支；
  8. 根据需要切回主开发分支；
  9. 更新主开发分支。

4. 切换分支前的安全检查

切换分支前，建议执行：

1
git status

根据结果选择处理方式：

  • 修改已经完成：提交后再切换；
  • 修改暂时不需要：确认无用后再丢弃；
  • 修改尚未完成：优先提交临时提交，或使用 Stash 临时保存；
  • 存在未跟踪文件：确认这些文件是否也需要保存。

不要在不清楚修改内容的情况下直接清理工作区，否则可能造成未提交代码丢失。

5. Stash（储藏）的正确用法

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

它不是：

  • 正式提交；
  • 远端分支；
  • 自动同步到云端的备份；
  • 适合长期保存代码的版本管理方式；
  • 分支切换的永久替代方案。

常用命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 保存修改并添加说明
git stash push -m "临时保存的修改"

# 同时保存未跟踪文件
git stash push -u -m "临时保存的修改"

# 查看储藏列表
git stash list

# 查看某条储藏内容
git stash show -p stash@{0}

# 恢复但暂不删除储藏
git stash apply stash@{0}

# 确认恢复正确后删除储藏
git stash drop stash@{0}

推荐优先使用 apply，检查恢复结果无误后再使用 drop。与直接使用 pop 相比，这样在发生冲突时更容易回退和核对。

长期或复杂修改更适合使用独立分支和正式提交，而不是长期留在 Stash 中。

6. UGit 中的状态标记与更新操作

UGit 中的颜色、圆点或数字标记通常表示仓库存在待处理状态，例如：

  • 远端有新提交等待拉取；
  • 本地有提交等待推送；
  • 工作区存在未提交修改；
  • 本地与远端分支出现分叉。

不同版本的 UGit 对图标含义可能有所不同，因此不要仅凭颜色直接操作。更新前应确认：

  1. 当前选择的是哪个仓库；
  2. 当前位于哪个本地分支；
  3. 当前分支跟踪哪个远端分支；
  4. 更新来源是否与当前分支一致；
  5. 工作区是否存在未提交修改；
  6. 更新操作实际使用 Merge、Rebase 还是 Fast-forward。

可以通过命令检查跟踪关系：

1
git branch -vv

如果当前位于 <功能分支>，并且更新来源是 origin/<功能分支>，更新通常只会影响该功能分支，不会自动把功能代码合并到主开发分支。

7. 长期功能分支的同步与维护

随着 <主开发分支> 持续更新，长期存在的 <功能分支> 可能逐渐落后。公共接口、框架、资源或配置结构发生变化后，旧功能分支可能出现冲突、无法构建或无法运行。

如果项目策略允许，可以定期将主开发分支的新内容同步到功能分支：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 更新主开发分支
git switch <主开发分支>
git pull --ff-only origin <主开发分支>

# 更新功能分支
git switch <功能分支>
git pull --ff-only origin <功能分支>

# 将主开发分支的新内容合入功能分支
git merge <主开发分支>

# 解决冲突并完成测试后推送
git push origin <功能分支>

同步方向为：

1
<主开发分支> → <功能分支>

这会让功能分支吸收主开发分支的新内容，但不会自动把功能代码反向合入主开发分支。

如果该功能明确要求保持独立，则不要执行反向合并：

1
<功能分支> → <主开发分支>

是否允许反向合并取决于团队的分支策略。正式功能最终需要上线时，通常仍需通过 Pull Request、Merge Request 或团队规定的发布流程合回目标分支。

建议同步时机

可以在以下情况同步：

  • 准备演示或测试功能之前；
  • 重新开始维护长期功能分支之前；
  • 主开发分支发生较大的框架、接口、资源或配置调整之后；
  • 功能分支无法构建、启动或出现明显兼容问题时；
  • 团队约定的定期同步时间点。

冲突处理原则

发生冲突时，通常应：

  • 理解两侧修改目的后再处理；
  • 公共框架和基础接口尽量适配主开发分支的新版本；
  • 保留功能分支自身需要的业务修改；
  • 不要在不检查内容的情况下直接“全部接受某一侧”；
  • 解决冲突后检查 git diff 和 git status；
  • 完成构建、启动和核心流程测试后再推送。

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

多仓库项目中，每个仓库都有独立的：

  • 当前分支；
  • 提交历史；
  • 远端跟踪关系；
  • 工作区状态；
  • 拉取和推送操作。

因此，在一个仓库中切换分支，不会自动切换其他仓库。

如果某项功能同时修改了代码、界面、资源和配置等多个仓库，应确保相关仓库处于相互兼容的分支与提交版本。

推荐流程：

  1. 确认该功能涉及哪些仓库；
  2. 记录各仓库当前分支和工作区状态；
  3. 在所有相关仓库中切换到对应功能分支；
  4. 分别拉取各仓库的远端最新版本；
  5. 完成修改和联调测试；
  6. 分别提交并推送各仓库；
  7. 记录相互兼容的提交版本；
  8. 完成后统一切回主开发分支。

如果不同仓库停留在不兼容的分支或提交上，可能出现：

  • 接口不匹配；
  • 界面或资源缺失；
  • 配置字段结构不一致；
  • 构建失败；
  • 启动或运行时报错；
  • 某个功能只完成了一部分。

多仓库切换前后，建议逐个仓库执行：

1
2
3
git status
git branch --show-current
git branch -vv

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

方案一：集中处理

适合偶尔维护功能分支：

  1. 平时保持在主开发分支；
  2. 需要处理功能时统一切换到功能分支；
  3. 集中完成修改、测试、提交和推送；
  4. 全部完成后再切回主开发分支。

这是最简单、最安全的方式。

方案二：使用 Git Worktree

如果需要长期并行维护多个分支，可以为不同分支准备独立工作目录：

1
git worktree add <新目录> <功能分支>

这样主目录可以保留在主开发分支，另一个目录固定使用功能分支，避免反复切换。

注意事项：

  • 同一个本地分支通常不能同时被两个 Worktree 检出；
  • 每个 Worktree 都需要独立管理工作区修改；
  • 多仓库项目需要为每个仓库分别配置；
  • 使用前应明确目录结构和团队约定，避免误操作。

10. 常见误区

误区一：切回主开发分支会删除功能代码

不会。只要代码已经提交，提交仍保存在对应分支中；如果已经推送，远端也有一份记录。

误区二：更新当前分支会自动合并另一个分支

通常不会。正常的 Pull 只会更新当前分支所跟踪的远端分支，除非手动选择了其他来源或执行了额外合并操作。

误区三：Stash 可以代替功能分支

不建议。Stash 适合短期临时保存，分支和提交才适合正式、长期维护。

误区四：多个仓库切换一个就够了

不一定。若功能横跨多个仓库，相关仓库应一起切换到兼容版本。

误区五：功能分支会自动获得主开发分支的新代码

不会。需要通过 Merge、Rebase、Cherry-pick 或重新创建分支等方式主动同步。

误区六：发生冲突时直接全部接受一侧即可

风险很高。冲突表示两侧修改重叠，必须理解代码含义后逐处处理，并在完成后测试。

11. 通用操作检查清单

切换前

  • 当前仓库是否正确；
  • 当前分支是否正确；
  • 是否有未提交或未跟踪的文件；
  • 修改是否已经提交、储藏或确认可以丢弃；
  • 多仓库之间是否需要一起切换。

更新前

  • 本地分支跟踪的远端分支是否正确；
  • 工作区是否干净；
  • 更新方式是否符合团队规范；
  • 是否可能产生冲突。

提交前

  • 是否只包含本次需要提交的文件；
  • 是否检查过差异；
  • 是否完成必要测试；
  • 提交说明是否清晰。

推送前

  • 推送目标仓库是否正确；
  • 推送目标分支是否正确；
  • 是否误将独立功能推送到主开发分支；
  • 多仓库相关提交是否完整。

12. 推荐原则总结

1
2
3
4
5
6
7
8
日常开发使用主开发分支
特定功能在对应功能分支中查看和修改
切换前先处理未提交修改
更新前确认本地分支与远端分支的对应关系
长期功能分支按团队策略吸收主开发分支的新内容
不要把 Stash 当作长期版本管理工具
多仓库项目要保持相关仓库的分支和版本兼容
任何合并、提交和推送操作前都先确认目标分支

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