-
Notifications
You must be signed in to change notification settings - Fork 0
GitHub PR
适用对象：仓库管理员、团队负责人、开源项目维护者
说明：本文基于 GitHub 仓库的 Settings → General → Pull Requests 页面设置进行详细讲解。
截图来源：用户提供的 GitHub Pull Requests 设置界面（2026 年版本）
GitHub 允许仓库管理员灵活控制 Pull Request 的合并方式。核心原则：
- 至少启用一种合并方式（Merge commit / Squash / Rebase）。
- 如果仓库的受保护分支（Protected Branch） 启用了 “Require linear history”（要求线性历史），则必须启用 Squash merging 或 Rebase merging。
- 合并方式可以同时开启多种，由 PR 作者在合并时自行选择。
作用： 将源分支（Head branch）的所有提交完整保留，通过创建一个新的 merge commit 合并到目标分支（Base branch）。
历史特点：
- 保留完整的开发历史（包括 feature branch 上的所有 commit）。
- 会产生一个额外的 merge commit，历史图呈现非线性（有分叉）。
适用场景：
- 需要完整追溯每个开发者的提交记录。
- 团队希望保留 feature branch 的完整开发轨迹。
- 适合小型团队或对历史完整性要求高的项目。
默认提交信息： 可自定义 merge commit 的默认模板，通常包含：
- PR 编号
- 源分支名称
- 合并人信息
优缺点：
- ✅ 历史最完整
- ❌ 历史不够干净，存在大量 merge commit
作用： 将源分支的所有提交压缩成一个单一的 commit，然后合并到目标分支。
历史特点：
- 目标分支历史保持干净、线性。
- 不会产生多余的 merge commit。
- 所有 feature 的改动被浓缩为一个 commit。
适用场景（强烈推荐）：
- 大多数开源项目和中大型团队的首选方式。
- 希望主分支（main/master）历史简洁易读。
- 适合 “功能开发完成 → 一次性合并” 的工作流。
- 与 Require linear history 配合良好。
默认提交信息： 可自定义 squash commit 的默认模板，建议包含：
- PR 标题
- PR 描述摘要
- 相关 Issue 编号
优缺点：
- ✅ 历史干净、线性
- ✅ 便于
git log --oneline查看 - ❌ 丢失了 feature branch 内部的详细提交历史（可通过 PR 页面查看）
作用： 将源分支的提交**变基（rebase）**到目标分支的最新提交之上，然后进行 fast-forward 合并。
历史特点：
- 保持完全线性历史，没有 merge commit。
- 每个 commit 的 hash 会改变（变基特性）。
适用场景：
- 严格要求线性历史的团队。
- 希望每个 commit 都独立、有意义，且历史可读性极高。
- 常与 Require linear history 规则一起使用。
注意事项：
- 变基会改变提交 hash，如果其他人已经基于该分支开发，需要谨慎操作（通常由 PR 作者自己 rebase）。
- GitHub 会在合并前自动处理 rebase。
优缺点：
- ✅ 历史最线性、最干净
- ❌ 可能引起 hash 变更的冲突风险（较少见）
作用： 当目标分支（Base branch） 有新提交时，在 Pull Request 页面自动显示 “Update branch” 按钮，提示开发者将 base 的最新更改合并或变基到自己的 PR 分支。
开启后的效果：
- PR 作者能一键更新分支，减少 merge conflict。
- 特别适合开启了 CI 检查的仓库（避免 CI 基于旧 base 运行）。
- 提升团队协作效率。
建议：强烈推荐开启（除非团队有其他强制同步机制）。
作用： 当 Pull Request 满足所有合并条件后（Required reviews、Required status checks、All conversations resolved 等），自动执行合并，无需人工点击 Merge 按钮。
适用场景：
- 仓库已开启严格的分支保护规则。
- 希望在 CI/CD 通过后自动合并，减少等待时间。
- 适合 “代码审查 + CI 通过 → 自动合并” 的高效流程。
使用方式：
- 管理员在仓库设置中开启此选项。
- PR 作者（或有权限者）在 PR 页面点击 “Enable auto-merge”。
- 满足条件后自动合并。
建议：
- 如果团队流程成熟，推荐开启。
- 可配合 Squash/Rebase 一起使用。
作用：
Pull Request 成功合并后，自动删除源分支（通常是 feature/xxx、fix/xxx 等临时分支）。
好处：
- 保持仓库分支列表整洁。
- 减少过时分支积累。
- 降低维护成本。
注意事项：
- 删除后仍可恢复（通过 GitHub 的 “Restore branch” 或本地 reflog）。
- 不会删除已合并到其他分支的重要分支。
建议：强烈推荐开启，这是 GitHub 最佳实践之一。
| 设置项 | 推荐状态 | 理由说明 | 适合项目类型 |
|---|---|---|---|
| Allow merge commits | 可选开启 | 保留完整历史时使用 | 小型团队、特殊需求 |
| Allow squash merging | 强烈推荐开启 | 历史干净、主流选择 | 大多数项目 |
| Allow rebase merging | 推荐开启 | 满足线性历史需求 | 严格线性历史团队 |
| Always suggest updating branches | 强烈推荐开启 | 减少冲突、提升效率 | 所有团队 |
| Allow auto-merge | 按需开启 | 自动化流程 | CI 严格的团队 |
| Automatically delete head branches | 强烈推荐开启 | 仓库整洁、行业标准 | 所有项目 |
由于 Starward 是 WinUI 3 + .NET 的桌面工具项目，建议采用以下配置：
-
同时开启 Squash merging + Rebase merging
- 给开发者灵活选择（简单功能用 Squash，复杂改动用 Rebase）。
- 开启 Always suggest updating pull request branches
- 开启 Automatically delete head branches
- 按需开启 Allow auto-merge（如果 CI 检查较多，建议开启）
- 关闭或按需开启 Allow merge commits（除非特别需要完整历史）
这样可以保持 main 分支历史清晰、专业，同时兼顾开发灵活性。
Q1: 为什么必须至少开启一种合并方式？
A: 否则无法合并任何 Pull Request。
Q2: 开启 Require linear history 后还能用 merge commit 吗？
A: 不能。必须使用 Squash 或 Rebase。
Q3: Squash 后还能在 Git 历史中看到原来的多个 commit 吗？
A: 不能在主分支历史看到，但可以在 PR 页面和 GitHub 的 commit 列表中查看原始提交。
Q4: 自动删除分支后还能恢复吗？
A: 可以。在 GitHub 仓库的 “Branches” 页面点击 “Show deleted branches” 即可恢复。
Q5: Auto-merge 和分支保护规则冲突吗？
A: 不冲突。Auto-merge 只有在所有保护规则满足后才会执行。
文档生成时间：2026-06-03
维护建议：定期检查 GitHub 官方更新，部分 UI 文案可能随版本微调。
本文档可直接用于团队 Wiki、仓库 README 或新成员 onboarding 材料。