SuperAPI AI 工具集

git-branch-pr-workflow

编程与开发

查看项目

更新于 11-11 01:10

技能介绍

用途

本技能为开发者提供关于 Git 分支管理、拉取请求(PR)工作流和 GitHub 集成的专家指导,重点采用现代 Git 命令和线性历史实践。其核心目标是减少本地分支管理开销、保持提交历史整洁,并规范 PR 创建流程。

主要能力

主分支开发模式(推荐)

直接在本地 main 分支上进行开发,然后将提交推送到远程功能分支以创建 PR。基本工作流如下:

# 所有工作都在 main 上进行
git switch main
git pull origin main

# 在 main 上修改并提交
git add file.ts
git commit -m "feat(auth): add OAuth2 support"

# 推送到远程功能分支(作为 PR 目标)
git push origin main:feat/auth-oauth2

# 使用 GitHub MCP 创建 PR(head: feat/auth-oauth2, base: main)

该模式的优势包括:无需在本地分支间切换、始终基于最新的 main、本地状态干净、远程分支为临时性(PR 合并后删除)、心智模型简单(一个本地分支,多个远程目标)。

多 PR 工作流(顺序提交)

当 main 上存在属于多个 PR 的提交时,可将特定提交范围推送到不同的远程分支:

# 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

# 将前两个提交推送到 auth 功能分支
git push origin abc1234^..def5678:feat/auth-oauth2

# 将剩余提交推送到 fix 分支
git push origin ghi9012^..ghi9012:fix/api-timeout

# 替代方案:从特定提交推送到 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 推送到远程分支

现代 Git 命令(2025)

使用专用命令替代多用途的 git checkout:

分支切换:

git switch feature-branch          # 替代 git checkout feature-branch
git switch -c new-feature          # 替代 git checkout -b new-feature
git switch -                       # 替代 git checkout -
git switch -c feature --track origin/feature
git switch -C force-recreate-branch

文件恢复:

git restore --staged file.txt      # 替代 git reset HEAD file.txt
git restore --staged .             # 替代 git reset HEAD .
git restore file.txt               # 替代 git checkout -- file.txt
git restore .                      # 替代 git checkout -- .
git restore --source=HEAD~2 file.txt    # 替代 git checkout HEAD~2 -- file.txt
git restore --source=main --staged .    # 替代 git reset main .

命令迁移对照:

旧命令 现代替代 用途
git checkout branch git switch branch 切换分支
git checkout -b new git switch -c new 创建并切换
git checkout -- file git restore file 丢弃更改
git reset HEAD file git restore --staged file 取消暂存
git checkout HEAD~1 -- file git restore --source=HEAD~1 file 从提交恢复

分支命名约定

结构化分支名称格式:{type}/{description}-{YYYYMMDD}(日期可选但推荐用于清晰性)。

类型包括:

  • feat/ — 新功能
  • fix/ — 缺陷修复
  • chore/ — 维护、依赖、linter 修复
  • docs/ — 文档变更
  • refactor/ — 代码重构
  • hotfix/ — 紧急生产修复

示例:

git switch -c feat/payment-integration
git switch -c fix/login-validation
git switch -c chore/update-dependencies
git switch -c hotfix/security-patch

线性历史工作流

主干开发: 首选主分支开发模式(见上),无需本地功能分支。

本地功能分支(替代方案): 适用于复杂多日工作。功能分支生命周期建议不超过 2 天,每日变基保持最新,PR 前通过交互式变基清理历史。

压缩合并策略: 保持 main 分支线性历史:

git switch main
git merge --squash feat/user-auth
git commit -m "feat: add user authentication system

- Implement JWT token validation
- Add login/logout endpoints
- Create user session management

Closes #123"

交互式变基: 在分享前清理提交:

git rebase -i HEAD~3

常用命令包括 pick(原样使用)、squash(合并到前一个提交)、fixup(合并但不编辑消息)、reword(修改提交消息)、drop(删除提交)。

GitHub MCP 集成

使用 GitHub MCP 工具(mcp__github__*)而非 gh CLI 执行所有 GitHub 操作:

# 获取仓库信息
mcp__github__get_me()  # 获取已认证用户信息

# 列出和创建 PR
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"
)

# 更新 PR
mcp__github__update_pull_request(
  owner="owner",
  repo="repo",
  pullNumber=42,
  title="Updated title",
  state="open"
)

# 列出和创建 issue
mcp__github__list_issues(owner="owner", repo="repo")

使用方式

本技能以指导文档形式提供,开发者可按照其中的工作流示例和命令模式操作。主要包括:日常同步与变基、冲突解决、安全强制推送(使用 --force-with-lease)、PR 标题与正文模板、问题引用规范(如 Closes #123、Fixes #456)等。

适用场景

  • 需要规范 Git 分支管理和 PR 流程的开发团队
  • 希望保持线性提交历史、减少合并提交的项目
  • 使用 GitHub 进行代码协作并希望集成 MCP 工具的工作流
  • 需要处理多 PR 顺序提交、日常同步、冲突解决等复杂场景的开发者

限制

资料未提供关于该技能的具体安装方式、配置要求、收费模式、平台依赖或效果评估等信息。部分命令示例依赖 Git 2.23+ 版本和 GitHub MCP 环境。使用前请确认环境支持。