git-branch-pr-workflow

Git 分支 PR 工作流

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用替代方案……
设计整体分支 + PR 工作流（基于 main 分支的开发、MCP 集成）	使用 git-branch-naming 选择或审核单个分支名称
在 git switch、git restore 和推送功能分支模式之间进行选择	使用 git-rebase-patterns 清理线性历史并处理堆叠 PR
通过 GitHub MCP 工具而非 gh pr create 创建 PR	使用 git-pr 通过 gh CLI 从已推送的分支创建 PR
协调从提交到推送再到 PR 的端到端流程	使用 git-commit-push-pr 执行整合后的提交 + 推送 + PR 宏操作

关于分支管理、拉取请求工作流，以及使用现代 Git 命令和线性历史实践进行 GitHub 集成的专家指南。

核心专长

• 基于主分支的开发：在本地的 main 分支上工作，将代码推送到远程功能分支以创建 PR
• 现代 Git 命令：使用 git switch 和 git restore，而非 checkout
• 分支命名：参见 git-branch-naming 技能
• 线性历史：优先使用 rebase 的工作流和 squash 合并——高级模式请参见 git-rebase-patterns
• GitHub MCP 集成：使用 mcp__github__* 工具，而非 gh CLI

基于主分支的开发（首选）

直接在 main 分支上开发，将代码推送到远程功能分支以创建 PR。这样无需管理本地分支，减少额外开销。

基本工作流

# All work happens on main
git switch main
git pull origin main

# Make changes, commit on main
git add file.ts
git commit -m "feat(auth): add OAuth2 support"

# Push to remote feature branch (creates PR target)
git push origin main:feat/auth-oauth2

# Create PR using GitHub MCP (head: feat/auth-oauth2, base: main)

多 PR 工作流（顺序提交）

当 main 分支上有多个 PR 对应的提交时，可将特定提交范围推送到不同的远程分支：

# Commits on main:
# abc1234 feat(auth): add OAuth2 support       <- PR #1
# def5678 feat(auth): add token refresh        <- PR #1
# ghi9012 fix(api): handle timeout edge case   <- PR #2

# Push first 2 commits to auth feature branch
git push origin abc1234^..def5678:feat/auth-oauth2

# Push remaining commit to fix branch
git push origin ghi9012^..ghi9012:fix/api-timeout

# Alternative: push from a specific commit to HEAD
git push origin def5678..HEAD:fix/api-timeout

提交范围模式：

• git push origin <start>^..<end>:<remote-branch> - 推送提交范围（包含首尾提交）
• git push origin <commit>..<commit>:<remote-branch> - 推送范围（不包含起始提交）
• git push origin <commit>..HEAD:<remote-branch> - 从指定提交推送到当前 HEAD
• git push origin main:<remote-branch> - 将整个 main 分支推送到远程分支

优势

• 无需在本地切换分支 - 始终位于 main 分支
• 始终基于最新的 main - 不会出现分支偏移
• 本地状态整洁 - 无需清理过期分支
• 远程分支是临时的 - PR 合并后即删除
• 心智模型更简单 - 一个本地分支，多个远程目标

现代 Git 命令（2025）

使用 git switch 管理分支，使用 git restore 管理文件，而非 git checkout / git reset。命令形式和从旧命令迁移到现代命令的对照表，请参见 references/modern-git-commands.md。

分支命名

关于完整的分支命名约定，包括类型前缀、问题关联和验证模式，请参见 git-branch-naming。

快速参考： {type}/{issue}-{description}（例如，feat/123-user-auth）

线性历史工作流

首选上文介绍的基于主分支的开发。关于本地功能分支（多日或实验性工作）、squash 合并和交互式 rebase 清理，请参见 references/local-feature-branches.md。

高级 Rebase 模式

关于高级 rebase 技巧，包括 --reapply-cherry-picks、--update-refs、--onto、堆叠 PR 工作流和组合标志，请参见 git-rebase-patterns。

GitHub MCP 集成

所有 GitHub 操作均使用 GitHub MCP 工具：

# Get repository information
mcp__github__get_me()  # Get authenticated user info

# List and create PRs
mcp__github__list_pull_requests(owner="owner", repo="repo")
mcp__github__create_pull_request(
  owner="owner",
  repo="repo",
  title="feat: add authentication",
  head="feat/auth",
  base="main",
  body="## Summary\n- JWT authentication\n- OAuth support\n\nCloses #123"
)

# Update PRs
mcp__github__update_pull_request(
  owner="owner",
  repo="repo",
  pullNumber=42,
  title="Updated title",
  state="open"
)

# List and create issues
mcp__github__list_issues(owner="owner", repo="repo")

最佳实践

始终使用 --force-with-lease 强制推送，绝不要推送到 main 或共享分支。关于每日将分支 rebase 到 main 的例行操作和 rebase 冲突处理，请参见 references/local-feature-branches.md。

主分支保护

通过 GitHub MCP 配置分支规则，以确保线性历史：

# Require linear history (disable merge commits)
# Configure via GitHub settings or MCP tools
# - Require pull request reviews
# - Require status checks to pass
# - Enforce linear history (squash merge only)

分支比较：始终使用 origin/main

重要： 创建 PR 时比较分支，始终与 origin/main（或 origin/<base-branch>）比较，绝不要与本地 main 比较。本地 main 可能包含尚未合并到远程的提交，导致 PR 中包含无关更改。

为什么这很重要

# WRONG: compares against local main (may include unpushed commits)
git log main..HEAD --format='%s'
git diff main...HEAD --stat

# CORRECT: compares against remote main (matches what GitHub will show)
git fetch origin main
git log origin/main..HEAD --format='%s'
git diff origin/main...HEAD --stat

常见场景： 你在本地 main 上为一个 PR 提交更改，将其推送到功能分支，然后开始处理第二个 PR。如果与本地 main 比较，第二个 PR 的差异看起来是正确的。但如果第一个 PR 尚未合并，origin/main 就会落后；与其比较会发现，两个 PR 的更改都会被包含在内。

规则

1. 比较前始终先获取： git fetch origin main
2. 在所有用于 PR 上下文的 diff/log 命令中使用 origin/main
3. 创建分支时以 origin/main 为基础： git switch -c feat/foo origin/main
4. pr-context.sh 脚本会自动处理

收集 PR 上下文（推荐）

创建 PR 前，使用一条命令收集所有上下文：

# Gather PR context (defaults to main as base, compares against origin/main)
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-branch-pr-workflow/scripts/pr-context.sh"

# Specify different base branch (compares against origin/develop)
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-branch-pr-workflow/scripts/pr-context.sh" develop

该脚本会获取最新的远程状态，并与 origin/<base> 比较，以确保 PR 上下文准确。输出包括：分支信息、远程状态、提交范围和类型、差异统计、提交中找到的问题引用、现有 PR 检测结果，以及 CI 检查结果。使用此输出来撰写 PR 标题和正文。详情请参阅 scripts/pr-context.sh。

Pull Request 工作流

PR 标题格式

PR 标题使用约定式提交格式：

• feat: add user authentication
• fix: resolve login validation bug
• docs: update API documentation
• chore: update dependencies

PR 正文模板

## Summary
Brief description of changes

## Changes
- Bullet points of key changes
- Link related work

## Testing
How changes were tested

## Issue References

Closes #123

问题引用指南：

• 使用 Closes #N / Fixes #N / Resolves #N，在合并时自动关闭问题
• 使用 Refs #N / Related to #N 添加上下文，但不自动关闭问题
• 跨仓库：Fixes owner/repo#N
• 多个问题：Fixes #1, fixes #2, fixes #3（重复关键词）

创建 PR 的最佳实践

• 每个 PR 聚焦一项内容——只包含一项逻辑更改
• 保持 PR 精简——更易于审查（建议少于 400 行）
• 始终关联问题——使用 GitHub 自动链接格式，方便追踪：
  • 关闭关键词：Closes #123、Fixes #456、Resolves #789
  • 引用但不关闭：Refs #234、Related to #567
  • 跨仓库：Fixes owner/repo#123
  • 多个问题：Fixes #1, fixes #2（每个问题都重复关键词）
• 添加标签——使用 GitHub 标签进行分类
• 请求审阅者——需要时标记特定审阅者

故障排除与恢复

有关故障排除（分支分叉、按预期流程提交到 main、复杂的变基冲突）、安全操作指南（识别正常状态、需要确认的命令）和恢复工作流（提交前钩子修改文件、推送被拒绝、提交失败），请参阅 REFERENCE.md。