Git 分支拓扑实践

Git 分支拓扑实践

核心结论：

1. dev 分支永远不要merge master，而应使用rebase master
2. 上游upstream的代码只能进入“集成分支（integration）”，不能直接进入dev / master

这两条规则并非经验之谈，而是由 Git 提交拓扑（DAG）结构决定的必然结论。

一、背景：为什么很多 Git 仓库会“越用越乱”

在实际工程中，尤其是：

• fork 了 GitHub 项目
• 需要长期同步 upstream
• 同时存在master / dev等长期分支

很多仓库最终都会出现：

• 合并历史极其复杂
• 冲突反复出现
• --ff-only永远无法使用
• 无法判断“哪些代码是稳定的”

根本原因不是 Git 用错，而是分支拓扑模型错误。

二、规则一：dev 永远不要 merge master（使用 rebase）

2.1 规则描述

dev 分支不能通过git merge master来同步 master 的更新，
必须使用git rebase master。

这条规则的本质目标只有一个：

保持 dev 与 master 的拓扑结构“相似（同构）”。

2.2 理想的拓扑结构（同构）

master: A ─ B ─ C ─ D ─ E \ d1 ─ d2 ─ d3 (dev)

特点：

• dev = master + 私有提交
• merge-base(dev, master) 唯一且稳定
• dev 可以随时快进或回放

2.3 使用 rebase 同步 master（正确）

命令

gitcheckout devgitrebase master

拓扑变化

rebase 前：

A ─ B ─ C ─ D ─ E ─ F (master) \ d1 ─ d2 (dev)

rebase 后：

A ─ B ─ C ─ D ─ E ─ F (master) \ d1' ─ d2' (dev)

结论：

• dev 的历史被“重新贴”到 master 之后
• 拓扑结构与 master 完全一致

2.4 使用 merge 同步 master（错误）

错误命令

gitcheckout devgitmerge master

产生的拓扑

A ─ B ─ C ─ D ─ E ─ F \ d1 ─ d2 ─── M (dev)

问题：

1. dev 出现额外 merge commit
2. dev 与 master 拓扑不再同构
3. merge-base 变得不可预测
4. 后续无法 fast-forward

三、规则二：upstream 只能进入“集成分支”

该部分详见如何优雅地同步和管理企业内部项目与上游开源代码的更新
本文是进一步的说明。

3.1 upstream 的拓扑风险

upstream 通常具有以下特征：

• 提交频繁
• 包含大规模重构
• 历史中可能存在大量 merge

拓扑示例：

U1 ─ U2 ─ M / \ U3 U4

upstream 的提交图通常是不可控的复杂子图。

3.2 错误做法：upstream 直接进入 dev / master

upstream → dev ↔ master

后果：

• dev 成为污染源
• master 继承复杂历史
• 冲突反复出现

3.3 正确模型：引入集成分支 integration

拓扑结构

upstream → integration → master → dev

integration 的角色：

拓扑缓冲区 / 防火墙

四、规则三的完整操作流程（含命令）

4.1 创建集成分支

gitcheckout mastergitcheckout -b integration

4.2 upstream → integration（唯一入口）

gitcheckout integrationgitfetch upstreamgitrebase upstream/main

冲突只允许在 integration 分支解决

4.3 integration → master

gitcheckout mastergitmerge integration

特点：

• 冲突概率极低
• master 只继承“结果”

4.4 master → dev（回到规则二）

gitcheckout devgitrebase master

五、完整拓扑演化示意

upstream: U1 ─ U2 ─ U3 ─ U4 | v integration: U1 ─ U2 ─ U3 ─ U4 ─ I1 ─ I2 | v master: M1 ─ M2 ─ I1 ─ I2 | v dev: M1 ─ M2 ─ I1 ─ I2 ─ d1 ─ d2

六、必须避免的操作清单

❌ 禁止：

gitmerge master# 在 dev 上gitmerge upstream# 在 dev / master 上

✅ 允许：

gitrebase master# dev 同步gitrebase upstream# 仅 integration

七、最终总结（工程级）

分支管理的本质不是“能不能合并”，
而是“拓扑是否长期可控”。

• rebase：保持拓扑同构
• integration：隔离上游复杂性
• master：永远稳定、线性、可发布

只要遵守这两条规则：

你的 Git 历史将长期保持清晰、可推导、可维护。