当前位置：首页 > news >正文

Git PR合并策略选择指南：历史可读性与协作效率的平衡

news 2026/6/7 5:46:02

Git 的 Pull Request 合并策略，不是按钮点一下就完事的“流程终点”，而是团队协作质量、历史可读性、故障回溯能力、甚至新人上手速度的“起点”。我带过 7 个不同规模的开发团队，从 3 人初创到 40+ 人的跨时区项目，踩过所有合并方式的坑——有人用 Squash 把三个月的迭代逻辑压成一行提交信息，结果线上出 Bug 时连哪次重构引入的问题都定位不了；也有人坚持 Create Merge Commit，结果主干日志里塞满“Merge branch 'feature/login' into main”这种毫无信息量的记录，CI 流水线失败后排查两小时才找到真正出问题的那一次 commit；还有团队盲目 Rebase and Merge，导致 feature 分支被强制重写，协作成员 fetch 后本地分支直接“失联”，集体卡在 git status 里发呆……这些都不是理论风险，是我凌晨三点帮同事救火时的真实截图。Git 本身没有对错，但合并方式选错了，就是把协作成本悄悄转嫁给了所有人。这篇文章不讲概念定义，只讲我在真实项目中怎么选、为什么这么选、每种方式在什么场景下是银弹、又在什么条件下会变成地雷。核心关键词就一个：Git。它不是命令行工具的代名词，而是团队代码契约的载体。你今天点下的那个合并按钮，本质上是在签署一份关于“我们如何共同维护这段历史”的协议。适合谁看？刚学会 git push 的新人、正在制定团队 Git 规范的 Tech Lead、被混乱提交历史折磨得想重开仓库的维护者，以及所有以为“能合进去就行”的开发者——这篇内容，就是给你补上那张没人教过的“合并决策地图”。

1. 合并策略的本质：不是操作差异，而是协作契约的三种形态

1.1 所有合并方式都绕不开的底层事实：Git 的“快进”与“三方合并”机制

要真正理解三种 PR 合并方式的区别，必须先回到 Git 最底层的两个动作：fast-forward（快进）和three-way merge（三方合并）。这不是教科书里的抽象概念，而是每次点击“Merge”按钮时，Git 实际执行的物理过程。

假设当前main分支最新提交是C3，而你的feature/login分支是从C3拉出来的，之后你本地提交了C4 → C5 → C6三个 commit。此时如果main分支自C3之后没有任何新提交，那么 Git 就可以执行 fast-forward：它不做任何合并计算，只是把main分支指针直接“快进”到C6的位置。整个过程就像把一列火车从第 3 节车厢直接推到第 6 节，中间轨道没被占用，所以无需调度。这种情况下，无论你在 GitHub 上选哪种合并方式，最终效果都一样——main指针指向C6，历史是线性的。

但现实项目中，这种情况极少发生。main几乎总是在你开发feature/login的同时，被其他同事合入了C7、C8甚至C9。这时main和feature/login已经分叉，Git 就必须启动三方合并：它会找出两个分支的最近共同祖先（common ancestor），也就是C3，然后把C3→C7/C8/C9（main 的变化）和C3→C4/C5/C6（feature 的变化）这两组修改，以C3为基准做差异比对，再尝试自动合并。如果冲突，就停下来等你手动解决；如果没有冲突，Git 就会生成一个新的 commit（我们叫它M1），它的父节点有两个：一个是C9（main 当前 tip），另一个是C6（feature 当前 tip）。这个M1就是真正的“合并提交”。

提示：GitHub 上所有 PR 合并按钮背后，本质都是在触发这个三方合并流程。区别只在于：是否生成这个M1提交？这个M1提交里包含哪些变更？以及feature分支的原始 commit 是否保留在主干历史中？这三个问题的答案，就定义了三种策略的根本差异。

1.2 Create Merge Commit：保留完整分支拓扑，代价是历史“毛刺化”

Create Merge Commit 是最忠实于 Git 原生行为的方式。它严格遵循三方合并逻辑，生成一个真实的、带有两个父节点的合并提交M1，并且完全保留feature/login分支上的所有原始 commit（C4, C5, C6），原封不动地接入主干历史。

它的价值，在于“可追溯性”被最大化。比如某天线上出现一个登录页样式错位的问题，你通过git blame定位到某个 CSS 文件的某一行，发现它是在C5中被修改的。你立刻就能git show C5看到当时的完整上下文：这次修改是为了解决 iOS Safari 下按钮点击无反馈的问题，配套改了 JS 的事件绑定逻辑，并且测试用例test_login_button_tap.js也同步更新了。所有线索都在一个 commit 里闭环。你不需要去猜“这个样式改动是不是和那次权限校验重构一起合进来的”，因为它们根本不在同一个 commit 里。

但代价也很真实：主干历史会变得“毛刺化”。想象一个持续半年的项目，平均每天有 3~5 个 PR 合入，每个 PR 平均含 4~6 个 commit。半年下来，main分支的提交图谱会像一张密集的蜘蛛网，大量Merge branch 'feature/xxx' into main提交穿插其中。如果你用git log --oneline查看，满屏都是a1b2c3d Merge branch 'feature/payment-v2' into main，真正承载业务逻辑的e4f5g6h Refactor payment gateway adapter反而被淹没。更麻烦的是，当你需要基于某个历史版本做 bisect（二分查找）时，Git 会把每一个Merge commit都当作一个潜在的“坏提交”候选，而它本身并不包含任何实际代码变更——这会让 bisect 过程多花 3~5 倍时间，因为你得手动跳过所有 merge 提交。

实操心得：我在一个金融风控系统中坚持了 18 个月的 Create Merge Commit，好处是审计时能精确到小时级还原每一次策略调整的完整链路；坏处是新来的 SRE 同事第一次跑git log --graph --all --simplify-by-decoration --oneline时，盯着终端沉默了三分钟，然后问我：“这个图……是需要配眼镜才能看懂吗？”——后来我们加了一条团队规范：所有 Merge commit 的 message 必须包含 Jira ID 和一句话摘要，例如Merge branch 'feature/risk-score-boost' into main (RISK-142: +15% false-negative reduction via new ML threshold)，至少让git log --oneline不再是纯噪音。

1.3 Squash and Merge：用“单次交付”换取历史整洁，但牺牲原子调试能力

Squash and Merge 的核心动作，是把feature/login分支上的全部 commit（C4, C5, C6）压缩（squash）成一个全新的 commitS1，然后把这个S1以普通提交（single-parent commit）的形式，追加到main分支的末尾。它不生成三方合并提交，main的历史依然是线性的，就像你一直在main上开发一样。

这种方式最大的优势，是主干历史极度“干净”。git log --oneline输出的结果，是一条清晰的、按时间顺序排列的业务演进脉络：a1b2c3d Add OAuth2 support for enterprise customers、e4f5g6h Fix race condition in session timeout handler、h7i8j9k Refactor notification service to use async queue……每个 commit 都是一个独立、完整、可描述的功能单元。CI 流水线失败时，你能一眼锁定是哪个功能引入的问题；产品同学问“XX 功能是哪天上线的”，你git log --since="2023-06-01" --grep="XX"一下就出结果；甚至做季度复盘时，导出git log --pretty=format:"%ad %s" --date=short | sort就能得到一份天然的版本功能清单。

但它付出的代价，是原子调试能力的永久丧失。还是那个登录页样式问题，git blame显示它来自S1。你git show S1，看到的是一大坨混合了 HTML 结构调整、CSS 样式重写、JS 表单验证逻辑、以及配套单元测试的变更。你无法快速判断：这个 CSS 修改，到底是为了解决 Safari 兼容性，还是为了适配新的设计稿？它和 JS 的修改是否存在耦合？测试用例的更新，是覆盖了所有新逻辑，还是只测了主路径？你必须手动翻看 PR 的原始讨论、对比 diff、甚至去查 Slack 记录，才能拼凑出上下文。在高压故障排查中，这种信息缺失就是致命的延迟。

注意：Squash 的“单次交付”属性，也意味着它天然不适合“渐进式重构”类工作。比如你用两周时间把一个 2000 行的旧服务逐步拆解为 5 个微服务模块，期间每天提交 1~2 个小 commit 来保证 CI 通过、避免阻塞他人。如果最后 squash 成一个Refactor user-service to microservices architecture，那这个 commit 的 diff 会超过 5000 行，Code Review 几乎不可能完成，CI 构建时间暴涨，而且一旦失败，你根本不知道是哪个模块的拆分出了问题。这类工作，必须用 Create Merge Commit 或 Rebase and Merge 来保留中间状态。

1.4 Rebase and Merge：用“线性叙事”平衡历史与调试，但要求强分支管控

Rebase and Merge 的逻辑，是先将feature/login分支上的所有 commit（C4, C5, C6），重新“播放”（replay）到当前main分支的最新提交（比如 C9）之后，生成一组全新的 commit（C4', C5', C6'），它们的 parent 是C9，而不是原来的C3。然后，再以 fast-forward 方式，把main分支指针直接指向C6'。整个过程不产生任何 merge commit，main历史保持绝对线性。

它的精妙之处在于：既获得了 Squash 的“线性历史”观感，又保留了 Create Merge Commit 的“多 commit 调试能力”。git blame依然能精准定位到C5'，git show C5'依然能看到那次 Safari 兼容性修复的完整上下文。你甚至可以用git log --oneline --first-parent main（只看第一父节点）得到一条干净的主干线，也可以用git log --oneline main（看所有节点）展开看到完整的 feature 分支贡献。

但它的脆弱性，也正源于此。Rebase 的本质是重写 commit 的哈希值。C4变成了C4'，它们是两个完全不同的对象。这意味着：如果你的feature/login分支已经推送到远程（origin/feature/login），而其他同事基于旧的C4在其上继续开发（比如拉出了feature/login-ui），那么当feature/login被 rebase 合并后，feature/login-ui的基线就“断掉”了。那位同事git pull时会看到大量冲突，或者更糟——他git push --force-with-lease强制推送，会把feature/login的新历史覆盖掉，导致团队协作彻底混乱。

实操心得：我在一个硬件驱动固件项目中推行 Rebase and Merge，前提是制定了铁律：所有 feature 分支必须设置为“不可推送”（即只在本地存在），PR 创建后立即启用 GitHub 的 “Require linear history” 保护规则，并且所有成员必须养成git fetch origin && git rebase origin/main的习惯。我们还写了一个 pre-commit hook，检查当前分支是否跟踪远程，如果是，则禁止 commit。这套组合拳下来，Rebase 的稳定性从 60% 提升到 99.8%。但代价是，新成员入职培训的第一课，就是《如何安全地 rebase》——这本身就是一种隐性的协作成本。

2. 核心细节解析与实操要点：参数、配置与不可见的陷阱

2.1 GitHub 后台配置：三种方式的开关逻辑与默认行为

很多人以为三种合并方式是“点了就生效”，其实 GitHub 的后台有一套精细的权限控制和默认策略。作为团队维护者，你必须亲手配置，否则新人随便点一下，就可能破坏全队的历史规范。

首先，进入仓库 Settings → Options → Merge button。这里你会看到三个复选框：

[x] Allow merge commits
[x] Allow squash merging
[x] Allow rebase merging

这三个选项不是“开启即可用”，而是“开启后，PR 页面才会显示对应按钮”。如果只勾选了前两个，那么 PR 页面就只有 “Create a merge commit” 和 “Squash and merge” 两个按钮，Rebase 选项根本不会出现。这是第一道防线。

更重要的是，默认合并方式（Default merge method）下拉菜单。它决定了当用户点击绿色的 “Merge pull request” 按钮（而不是下面三个具体按钮）时，GitHub 会执行哪一种策略。这个默认值，对新手极其危险。我见过太多团队把默认设为 Squash，结果一位实习生在 PR 描述里写了 “WIP: don’t merge yet”，但手滑点了那个大大的绿色按钮，结果所有未完成的实验性代码被一股脑 squash 进了 main，CI 直接挂掉。所以我的建议是：永远把默认合并方式设为 “Create a merge commit”。因为它是 Git 的“安全模式”——即使点错了，也只是多一个无害的 merge commit，不会丢失历史或重写分支。

提示：GitHub 还有一个隐藏配置项，在 Settings → Branches → Branch protection rules → Edit rule。在这里，你可以为main（或develop）分支启用 “Require linear history”。一旦开启，GitHub 就会强制禁用 Create Merge Commit，只允许 Squash 和 Rebase。这是推行线性历史的终极手段，但必须配合严格的 Code Review 流程，否则会极大增加 PR 合并阻力。

2.2 VS Code 插件与本地 Git 配置：让 IDE 成为你策略的延伸

很多开发者以为合并策略只在 GitHub Web 界面生效，其实 VS Code 的 GitHub Pull Requests & Issues 插件，以及本地 Git 配置，都能深度影响你的日常操作。

VS Code 插件在 PR 详情页右上角，提供了一个下拉菜单，让你选择合并方式。但它的行为有个关键细节：当你选择 “Squash and merge” 时，插件不会直接调用 GitHub API，而是先在本地执行git merge --squash <branch>，然后git commit，最后git push。这意味着，如果你本地的user.name和user.email配置错误（比如还是你上一家公司的邮箱），那么这个 squash commit 的 author 信息就会是错的，后续审计时会出大问题。我见过一个医疗 SaaS 项目，因为一位同事的 Git 邮箱没切过来，导致一个关键的 HIPAA 合规性修复 commit，author 显示为unknown@old-company.com，法务部直接发函要求追溯和修正。

因此，我强制团队在项目根目录下放置.gitconfig文件（并加入.gitignore防止误提交），内容如下：

[user] name = "Your Full Name" email = "your-team@current-company.com" [commit] gpgsign = true [merge] ff = only

最后一行ff = only是关键。它告诉 Git：任何 merge 操作，都只允许 fast-forward，禁止生成三方合并提交。这相当于在本地给 Create Merge Commit 加了一道锁。当你在 VS Code 里不小心点了 “Create a merge commit”，Git 会直接报错fatal: Not possible to fast-forward, aborting.，逼你停下来思考：是不是该用 rebase 了？是不是该先 fetch 更新 main 了？这个看似“阻碍效率”的配置，实则是防止低级错误的最强护栏。

2.3 提交信息（Commit Message）的黄金模板：让每种策略都物尽其用

无论你选哪种合并方式，提交信息的质量，直接决定了这个策略是锦上添花，还是画蛇添足。我总结了一套适用于所有场景的 “5W1H” 模板，已在 5 个不同技术栈项目中验证有效：

<type>(<scope>): <subject> <body> <footer>

<type>：固定为feat、fix、refactor、docs、test、chore。这是自动化脚本（如 semantic-release）的基础。
<scope>：模块名，如auth、payment、ui、api。它让git log --grep="auth"这类搜索成为可能。
<subject>：一句话摘要，50 字以内，用祈使句（如 “Add OAuth2 support” 而非 “Added OAuth2 support”）。
<body>：详细说明。必须回答：What changed? Why is it needed? How was it tested?这是 Squash 和 Rebase 场景下，替代原始 commit 信息的唯一载体。
<footer>：关联信息。Jira ID（RISK-142）、Breaking Change 声明（BREAKING CHANGE: ...）、Reviewed-by 签名。

对于 Create Merge Commit，这个模板主要用在feature分支的每个原始 commit 上。每个C4、C5都要严格遵守，这样git log --oneline才有意义。

对于 Squash and Merge，这个模板必须用在 squash 之后的那个最终 commit 上。我见过太多团队把 PR 标题（如 “Login Feature”）直接当 squash message，结果git log里全是废话。正确的做法是：在 VS Code 的 squash commit 编辑框里，手动输入符合模板的完整信息，把 PR 描述、评论中的关键结论、测试结果，全部浓缩进来。

对于 Rebase and Merge，这个模板同样适用，但要注意：rebase 过程中，Git 会默认沿用原始 commit 的 message。所以你必须在 rebase 前，确保所有原始 commit 都已按模板规范好。一个实用技巧是，在git rebase -i HEAD~3的交互式编辑器里，把所有pick改成reword，然后逐个编辑 message。

注意：GitHub 的 “Squash and merge” 按钮，有一个极易被忽略的细节——它默认会把 PR 的标题和描述，作为 squash commit 的 message。这非常危险！因为 PR 标题往往是 “WIP: Login Page UI” 这种草稿状态，描述里可能包含 “TODO: add error handling” 这样的未完成项。所以，永远不要依赖 GitHub 的默认 message，务必在点击前，手动清空并重写。我们团队在.github/PULL_REQUEST_TEMPLATE.md里，第一行就写着：“⚠️ Squash message must follow 5W1H template. Do NOT use PR title/description.”。

2.4 CI/CD 流水线的适配：不同策略对构建、测试、部署的影响

合并策略的选择，会直接影响你的 CI/CD 流水线设计。一个没适配好的流水线，会让再好的策略变成灾难。

首先是构建缓存（Build Cache）。Create Merge Commit 因为保留了所有原始 commit，所以main分支的每次构建，都可以精准复用C4、C5、C6对应的缓存块。而 Squash and Merge 生成的是一个全新的S1，它的 hash 和任何旧 commit 都无关，所以构建缓存命中率会暴跌。我们的 Node.js 项目，在切换到 Squash 后，CI 构建时间从平均 4.2 分钟涨到 7.8 分钟。解决方案是：在S1的 commit message footer 里，强制加入CACHE_KEY: feature-login-20230717，然后在 CI 脚本里，用这个 key 去主动拉取缓存。

其次是测试策略。Create Merge Commit 天然支持 “per-commit testing” —— 你可以为每个C4、C5单独运行单元测试，快速定位问题。而 Squash 后，所有测试都只能在S1上运行，一旦失败，你得手动拆解 diff。为此，我们为 Squash 场景定制了一个 “Squash Pre-Check” 流水线：它会在 PR 关闭前，自动 checkoutfeature分支，运行git rebase -i --exec "npm test" HEAD~3，确保每一个原始 commit 都能通过测试，才允许 squash。

最后是部署与发布。Rebase and Merge 的线性历史，让git describe --tags这类语义化版本生成工具工作得无比顺畅。而 Create Merge Commit 的复杂图谱，会让describe返回类似v2.1.0-34-ga1b2c3d这样难以解读的版本号。我们的解决方案是：在 Create Merge Commit 场景下，放弃describe，改用git tag -l --sort=-v:refname | head -n1获取最新 tag，再结合git rev-list --count <latest-tag>..main计算距上次发布的 commit 数，生成v2.1.0+42这样的版本号，既准确又易读。

3. 实操过程与核心环节实现：从 PR 创建到合并完成的全流程拆解

3.1 场景设定与初始状态：一个真实的电商项目片段

为了让你能跟着实操，我们设定一个具体的、有血有肉的场景。这是一个名为shopify-plus的电商 SaaS 平台，后端用 Go 编写，前端用 React，部署在 Kubernetes 上。当前main分支的状态如下（git log --oneline -n 5）：

a1b2c3d (HEAD -> main) feat(api): add webhook retry mechanism for payment failures e4f5g6h fix(auth): resolve JWT token expiration race condition h7i8j9k refactor(cart): extract cart validation logic to dedicated service k0l1m2n docs: update API reference for /v2/orders endpoint m3n4o5p chore(deps): bump golang.org/x/crypto from v0.12.0 to v0.13.0

现在，你要开发一个新功能：为商家后台添加“订单导出为 Excel”功能。你从main拉出分支feature/export-excel，并在接下来的两天里，完成了以下工作：

C1:feat(export): add basic CSV export endpoint
（实现了基础的 CSV 导出，支持按日期范围筛选）
C2:fix(export): handle nil pointer panic when no orders found
（修复了空订单列表时的 panic）
C3:feat(export): add Excel (.xlsx) format support using github.com/tealeg/xlsx
（集成了 xlsx 库，支持 Excel 格式）
C4:test(export): add integration tests for both CSV and Excel exports
（补充了端到端测试）

此时，feature/export-excel分支的git log --oneline是：

w8x9y0z (HEAD -> feature/export-excel) test(export): add integration tests for both CSV and Excel exports v7u8t9s feat(export): add Excel (.xlsx) format support using github.com/tealeg/xlsx r6s5t4u fix(export): handle nil pointer panic when no orders found q5p4o3n feat(export): add basic CSV export endpoint

而main分支在这两天里，又被其他同事合入了两个新 commit：

a1b2c3d (HEAD -> main) feat(api): add webhook retry mechanism for payment failures e4f5g6h fix(auth): resolve JWT token expiration race condition ...（之前的提交）

所以，main和feature/export-excel已经分叉，共同祖先是m3n4o5p。

3.2 Create Merge Commit 实操：保留所有痕迹，构建可审计历史

第一步：确保本地环境同步。在feature/export-excel分支下，执行：

git fetch origin git rebase origin/main # 这一步可选，但强烈推荐，确保你的 feature 基于最新 main

rebase后，你的feature/export-excel分支会变成：

w8x9y0z' test(export): add integration tests for both CSV and Excel exports v7u8t9s' feat(export): add Excel (.xlsx) format support using github.com/tealeg/xlsx r6s5t4u' fix(export): handle nil pointer panic when no orders found q5p4o3n' feat(export): add basic CSV export endpoint

注意末尾的'，表示 commit hash 已变，但 message 不变。

第二步：在 GitHub 上创建 PR，目标分支为main。在 PR 描述中，清晰写明：

What: 商家后台新增订单导出功能，支持 CSV 和 Excel 两种格式。
Why: 客户反馈现有 CSV 导出无法满足财务部门对格式和样式的严格要求。
How: 使用tealeg/xlsx库生成 Excel，所有导出逻辑复用现有 CSV 的数据查询层，确保一致性。
Test: 新增 4 个集成测试，覆盖空订单、单订单、多订单、超长字段等边界场景。

第三步：等待 Code Review 通过后，点击 “Create a merge commit” 按钮。GitHub 会生成一个新的合并提交M1，其 message 默认为 “Merge pull request #123 from your-name/feature/export-excel”。但这是错误的！你必须在点击前，手动编辑 message，改为：

Merge branch 'feature/export-excel' into main (SHOP-456: Add Excel export for merchant dashboard) * feat(export): add basic CSV export endpoint * fix(export): handle nil pointer panic when no orders found * feat(export): add Excel (.xlsx) format support using github.com/tealeg/xlsx * test(export): add integration tests for both CSV and Excel exports Reviewed-by: Alice Chen <alice@company.com>

第四步：合并完成后，main的git log --oneline -n 10将是：

z1a2b3c (HEAD -> main) Merge branch 'feature/export-excel' into main (SHOP-456: Add Excel export for merchant dashboard) a1b2c3d feat(api): add webhook retry mechanism for payment failures e4f5g6h fix(auth): resolve JWT token expiration race condition h7i8j9k refactor(cart): extract cart validation logic to dedicated service k0l1m2n docs: update API reference for /v2/orders endpoint m3n4o5p chore(deps): bump golang.org/x/crypto from v0.12.0 to v0.13.0 w8x9y0z test(export): add integration tests for both CSV and Excel exports v7u8t9s feat(export): add Excel (.xlsx) format support using github.com/tealeg/xlsx r6s5t4u fix(export): handle nil pointer panic when no orders found q5p4o3n feat(export): add basic CSV export endpoint

实操心得：这个历史图谱，就是你的“时间机器”。如果一周后发现 Excel 导出在特定字体下会崩溃，你git bisect start HEAD q5p4o3n，Git 会自动帮你二分，最终精准定位到v7u8t9s这个 commit，然后git show v7u8t9s就能看到当时集成tealeg/xlsx的全部细节，包括它依赖的 Go 版本、已知的 issue 链接、以及你写的临时 workaround 注释。这种能力，在 Create Merge Commit 下是开箱即用的。

3.3 Squash and Merge 实操：打造一条干净、可交付的主干线

第一步：同样从同步开始。但在feature/export-excel分支下，我们不 rebase，而是直接git fetch origin，确保你知道main的最新状态是a1b2c3d。

第二步：创建 PR，描述同上。但这次，你明确在 PR 描述的开头加上：

⚠️ This PR MUST be merged with "Squash and merge". Reason: The feature involves multiple small commits that are not meaningful on their own (e.g., C2 is just a panic fix for C1). A single, well-documented delivery commit provides the clearest signal for release notes and audit.

第三步：Review 通过后，点击 “Squash and merge” 按钮。关键来了：GitHub 会弹出一个编辑框，预填充了 PR 标题和描述。你必须全部删除，然后手动输入：

feat(export): add Excel export for merchant dashboard (SHOP-456) Implement full Excel (.xlsx) export functionality for the merchant order list, supporting date-range filtering and all existing CSV data fields. Why: - Customers require Excel format for financial reconciliation and reporting. - Existing CSV lacks formatting control (fonts, colors, formulas). How: - Integrated github.com/tealeg/xlsx v1.0.0. - Reused existing /api/v2/orders/export endpoint, added 'format=xlsx' query param. - All business logic (filtering, pagination, data mapping) is shared with CSV export. Testing: - Added 4 new integration tests covering edge cases. - Manual QA on Chrome, Safari, Edge with 10k+ order datasets. BREAKING CHANGE: None. Backward compatible with existing CSV export. Reviewed-by: Bob Smith <bob@company.com>

第四步：点击确认。main分支将新增一个 commit：

x9y0z1a (HEAD -> main) feat(export): add Excel export for merchant dashboard (SHOP-456) a1b2c3d feat(api): add webhook retry mechanism for payment failures e4f5g6h fix(auth): resolve JWT token expiration race condition ...

注意：这个x9y0z1a的 diff，会包含C1到C4的全部变更。所以，你的 CI 流水线必须能处理这种“大 diff”构建。我们为此专门优化了 Go 的构建脚本，使用-mod=readonly和GOCACHE环境变量，确保即使 diff 很大，也能复用之前编译过的依赖包。

3.4 Rebase and Merge 实操：在不牺牲调试的前提下，获得线性历史

第一步：这是最需要谨慎的。在feature/export-excel分支下，执行：

git fetch origin git rebase -i origin/main

Git 会打开一个编辑器，列出q5p4o3n到w8x9y0z的所有 commit。默认是pick。如果你觉得C2（panic fix）和C1（CSV export）逻辑紧密，可以把它改成fixup，这样C2的变更会被自动合并到C1中，不产生独立 commit。最终，你可能得到：

pick q5p4o3n feat(export): add basic CSV export endpoint fixup r6s5t4u fix(export): handle nil pointer panic when no orders found pick v7u8t9s feat(export): add Excel (.xlsx) format support using github.com/tealeg/xlsx pick w8x9y0z test(export): add integration tests for both CSV and Excel exports

保存退出后，Git 会依次 rebase。过程中，如果遇到冲突（比如C3修改的文件，main也修改了），它会暂停，让你解决。解决后git add . && git rebase --continue。

第二步：rebase 完成后，你的分支变成了：

z1a2b3c (HEAD -> feature/export-excel) test(export): add integration tests for both CSV and Excel exports y0z1a2b feat(export): add Excel (.xlsx) format support using github.com/tealeg/xlsx x9y0z1a feat(export): add basic CSV export endpoint

所有 commit 的 hash 都变了，但 message 保持不变（除了你用reword修改的）。

第三步：强制推送（因为历史被重写了）：

git push --force-with-lease origin feature/export-excel

--force-with-lease比--force安全得多，它会检查远程分支是否被他人更新，如果被更新了，会拒绝推送，避免覆盖他人工作。

第四步：在 GitHub PR 页面，点击 “Rebase and merge”。GitHub 会执行git merge --ff-only，将main指针直接指向z1a2b3c。最终main的历史是：

z1a2b3c (HEAD -> main) test(export): add integration tests for both CSV and Excel exports y0z1a2b feat(export): add Excel (.xlsx) format support using github.com/tealeg/xlsx x9y0z1a feat(export): add basic CSV export endpoint a1b2c3d feat(api): add webhook retry mechanism for payment failures e4f5g6h fix(auth): resolve JWT token expiration race condition ...

提示：这个历史，git log --oneline看起来和 Squash 一样干净，但git log --oneline --all会展开看到所有分支。更重要的是，git blame依然能精准定位到y0z1a2b，git show y0z1a2b依然能看到 Excel 集成的全部上下文。你得到了 Squash 的“形”，和 Create Merge Commit 的“神”。